Unit 3 · Lesson 9 Intermediate ⏱ ~45 minutes

Networking

Modern applications rarely work in isolation — they fetch data from web services, submit forms, consume APIs, and communicate with the outside world. In this lesson you'll learn how to make HTTP requests from HyperXTalk, handle JSON responses, send data with POST, and deal gracefully with network errors.

🎯 Learning Objectives
  • Fetch data from a URL using get URL
  • Parse JSON responses using JsonImport
  • Send data to a server using post data to URL
  • Set HTTP headers with set the httpHeaders to
  • Handle network errors by checking the result

🌐 GET Requests

The simplest networking operation is a GET request — fetching the contents of a URL. HyperXTalk makes this as easy as a single line. The response is placed into the special variable it:

on mouseUp local tURL, tResponse put "https://jsonplaceholder.typicode.com/todos/1" into tURL get URL tURL put it into tResponse answer tResponse end mouseUp
Script editor showing a simple GET request
A simple GET request — click to enlarge

get URL tURL is synchronous — HyperXTalk waits for the response before continuing. The raw response body lands in it, which you immediately store in a local variable before doing anything else with it.

💡 The examples in this lesson use JSONPlaceholder (jsonplaceholder.typicode.com) — a free, public test API that returns realistic fake data. It's perfect for learning and prototyping without needing your own server.

📋 Parsing JSON

Most modern web APIs return data in JSON format. HyperXTalk's JsonImport function parses a JSON string into a HyperXTalk array, letting you access individual fields by name:

on mouseUp local tURL, tResponse, tData put "https://jsonplaceholder.typicode.com/todos/1" into tURL get URL tURL put it into tResponse put JsonImport(tResponse) into tData answer tData["title"] end mouseUp
Script editor showing GET with JsonImport
Fetching and parsing JSON in one handler — click to enlarge

The JSON response from this endpoint looks like:

JSON response
{ "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }

After JsonImport, the array tData contains each field accessible by its key — so tData["title"] gives you "delectus aut autem", tData["completed"] gives "false", and so on.

Nested JSON and Arrays

For JSON arrays, JsonImport creates a numerically indexed array. For nested objects, you chain the keys:

-- JSON array: access first item put tData[1]["title"] into tFirstTitle -- Loop through all items in a JSON array local tI repeat with tI = 1 to the number of elements of tData put tData[tI]["title"] & return after tOutput end repeat

📤 POST Requests

To send data to a server — submitting a form, creating a record, sending a message — use post data to URL. You set the request headers first, then post the data:

on mouseUp local tURL, tData, tResponse put "https://jsonplaceholder.typicode.com/posts" into tURL put "title=Hello&body=HyperXTalk&userId=1" into tData set the httpHeaders to "Content-Type: application/x-www-form-urlencoded" post tData to URL tURL if the result is not empty then answer "Error: " & the result else answer "Posted successfully!" end if end mouseUp
Script editor showing a POST request with headers and error handling
A POST request with headers and error handling — click to enlarge

🏷️ HTTP Headers

set the httpHeaders to lets you set request headers before a GET or POST. You can set multiple headers by separating them with a return character:

-- Single header set the httpHeaders to "Content-Type: application/json" -- Multiple headers set the httpHeaders to \ "Content-Type: application/json" & return & \ "Authorization: Bearer mytoken123" -- Post JSON data put '{"title":"Hello","body":"HyperXTalk"}' into tData post tData to URL tURL
🟢 HTTP headers persist between requests in the same stack session. If you set an Authorization header for one request, it will be sent with subsequent requests too. Reset it with set the httpHeaders to empty when you're done.

⚠️ Error Handling

Network requests can fail for many reasons — no internet connection, server errors, invalid URLs, timeouts. For POST requests, the result contains an error message if something went wrong, or is empty on success. Always check it:

post tData to URL tURL if the result is not empty then -- Something went wrong answer "Network error: " & the result exit mouseUp end if -- Success — continue processing

For GET requests, a failed request will typically return an error string rather than the expected data. A simple defensive check is to test whether the response looks like what you expected before processing it:

get URL tURL put it into tResponse -- Check it looks like JSON before parsing if char 1 of tResponse is "{" or char 1 of tResponse is "[" then put JsonImport(tResponse) into tData else answer "Unexpected response: " & tResponse end if
⚠️ Network requests are synchronous in HyperXTalk — your stack will be unresponsive while waiting for a response. For long-running requests, consider showing a "Loading…" message to the user before the request and clearing it afterwards.
🛠️ Exercise — A Simple API Browser

In this exercise you'll build a simple app that fetches a to-do item from the JSONPlaceholder API by ID and displays its details. Click any thumbnail to enlarge it.

  1. Create a new stack. Add a Field named IDInput for entering an item ID (1–200), a Button labelled Fetch Item, and three fields with Lock text enabled: TitleOutput, CompletedOutput, and UserOutput.
  2. Edit the script of the Fetch Item button:
    button "Fetch Item"
    on mouseUp local tID, tURL, tResponse, tData put the text of field "IDInput" into tID if tID is empty or tID is not a number then answer "Please enter a number between 1 and 200." exit mouseUp end if put "https://jsonplaceholder.typicode.com/todos/" \ & tID into tURL get URL tURL put it into tResponse if char 1 of tResponse is not "{" then answer "Could not fetch item " & tID exit mouseUp end if put JsonImport(tResponse) into tData set the text of field "TitleOutput" to tData["title"] set the text of field "CompletedOutput" to tData["completed"] set the text of field "UserOutput" to "User " & tData["userId"] end mouseUp
    GET and JsonImport
    GET + JsonImport
  3. Switch to Browse mode. Type a number between 1 and 200 and click Fetch Item. The three output fields should populate with the title, completed status, and user ID from the API.

Bonus challenge: The JSONPlaceholder API also has a /users/ endpoint. After fetching the to-do item, make a second GET request to https://jsonplaceholder.typicode.com/users/[userId] and display the user's name instead of just their ID.

📝 Review Questions
Question 1
Where does the response from get URL tURL go?
Into the special variable it. You should immediately store it in a local variable with put it into tResponse, since it is overwritten by the next operation that produces a result.
Question 2
What does JsonImport return, and how do you access a field from it?
JsonImport returns a HyperXTalk array. You access fields using the key name in square brackets — e.g. tData["title"]. For JSON arrays, items are accessed by number — e.g. tData[1]["title"].
Question 3
What is the difference between get URL and post data to URL?
get URL fetches data from a server without sending a body — used for reading data. post data to URL sends a data payload to the server — used for submitting forms, creating records, or sending data to an API.
Question 4
How do you set multiple HTTP headers for a request?
Separate them with a return character: set the httpHeaders to "Content-Type: application/json" & return & "Authorization: Bearer mytoken". Remember to reset with set the httpHeaders to empty when done, as headers persist between requests.
Question 5
How do you detect whether a POST request failed?
Check the result after the post — if it is not empty, an error occurred and the result contains the error message. If it is empty, the request succeeded.
← Lesson 8: File Handling