How-To Guide ⏱ ~25 minutes

Making HTTP Requests

HyperXTalk's Internet library makes it straightforward to fetch data from the web, submit forms, and call REST APIs — all from within your scripts. This guide covers GET and POST requests, setting custom headers, parsing JSON responses, async callbacks, and error handling.

What you'll cover

Simple GET requests using the URL keyword
POST requests with form data using libURLFormData
Setting custom HTTP headers
Parsing JSON responses
Async downloads with callback messages
Checking for errors

GET Requests

The simplest way to fetch data from a URL is with the URL keyword — just get or put the URL into a variable. This is a synchronous request that blocks until the response arrives:

local tResponse
put URL "https://api.example.com/data" into tResponse

if the result is not empty then
   throw "GET request failed:" && the result
end if

put tResponse into field "Output"

For non-blocking background downloads, use the load command with a callback message. The handler continues running while the download happens in the background:

stack script
on fetchData
   load URL "https://api.example.com/data" with message "dataLoaded"
end fetchData

on dataLoaded pURL, pStatus
   if pStatus is "cached" then
      local tResponse
      put URL pURL into tResponse
      put tResponse into field "Output"
   else
      answer "Download failed:" && libURLErrorData(pURL)
   end if
end dataLoaded

💡 After a load completes successfully, the data is in the cache. Retrieve it with put URL pURL into tResponse — HyperXTalk serves it from the cache automatically.

POST Requests

Use libURLFormData to format key-value pairs into a URL-encoded POST body, then post it to the URL:

stack script
on submitForm
   local tData, tResponse

   put libURLFormData("name", field "Name", \
                        "email", field "Email", \
                        "message", field "Message") into tData

   post tData to URL "https://api.example.com/contact"
   put it into tResponse

   if the result is not empty then
      throw "POST request failed:" && the result
   end if

   answer "Submitted successfully!"
end submitForm

libURLFormData accepts any number of key-value pairs and formats them as key=value&key=value. The Content-Type header is automatically set to application/x-www-form-urlencoded — no need to set it manually.

Custom Headers

Use libURLSetCustomHTTPHeaders to set headers for the next request — useful for sending API keys, Bearer tokens, or specifying Content-Type: application/json:

stack script
on fetchWithAuth pToken
   local tHeaders, tResponse

   put "Accept: application/json" & return into tHeaders
   put tHeaders & "Authorization: Bearer " & pToken into tHeaders

   libURLSetCustomHTTPHeaders tHeaders
   put URL "https://api.example.com/protected" into tResponse

   if the result is not empty then
      throw "Request failed:" && the result
   end if

   return tResponse
end fetchWithAuth

⚠️ libURLSetCustomHTTPHeaders replaces all default headers for the next request only — after the request completes, headers revert to the defaults. If you're making multiple requests with the same headers, call libURLSetCustomHTTPHeaders before each one.

Working with JSON

HyperXTalk includes a JSON library for parsing responses. Use JsonToArray to convert a JSON string into a HyperXTalk array, and ArrayToJson to convert an array to JSON for sending:

stack script
function fetchJSON pURL
   local tResponse, tData

   libURLSetCustomHTTPHeaders "Accept: application/json"
   put URL pURL into tResponse

   if the result is not empty then
      throw "fetchJSON error:" && the result
   end if

   JsonToArray tResponse, tData
   return tData
end fetchJSON

Posting JSON works similarly — build your array, convert it, set the Content-Type header, then post it:

stack script
on postJSON pURL, pDataA
   local tJSON, tHeaders

   ArrayToJson pDataA, tJSON

   put "Content-Type: application/json" & return into tHeaders
   put tHeaders & "Accept: application/json" into tHeaders
   libURLSetCustomHTTPHeaders tHeaders

   post tJSON to URL pURL

   if the result is not empty then
      throw "postJSON error:" && the result
   end if
end postJSON

Async Requests with Progress Callbacks

For large downloads where you want to show progress, use libURLSetStatusCallback to receive periodic status updates during the transfer:

stack script
on startDownload
   libURLSetStatusCallback "downloadProgress", the long ID of me
   load URL "https://api.example.com/large-file" with message "downloadComplete"
end startDownload

on downloadProgress pURL, pStatus
   local tReceived, tTotal, tPercent

   if item 1 of pStatus is "loading" then
      put item 2 of pStatus into tReceived
      put item 3 of pStatus into tTotal

      if tTotal is not empty and tTotal > 0 then
         put round(tReceived / tTotal * 100) into tPercent
         set the thumbPosition of scrollbar "Progress" to tPercent
      end if
   end if
end downloadProgress

on downloadComplete pURL, pStatus
   -- Turn off the callback
   libURLSetStatusCallback

   if pStatus is "cached" then
      put URL pURL into field "Output"
   else
      answer "Download failed:" && libURLErrorData(pURL)
   end if
end downloadComplete

💡 The status parameter during loading is a comma-delimited string: loading,bytesReceived,bytesTotal. The total may be empty if the server doesn't report the file size. Always check before dividing!

Error Handling

For synchronous requests, check the result immediately after the request. For async requests via load, check the status parameter in the callback and use libURLErrorData to get the error detail:

stack script
-- Synchronous error check
put URL "https://api.example.com/data" into tResponse
if the result is not empty then
   throw "Request failed:" && the result
end if

-- Async error check in callback
on myCallback pURL, pStatus
   switch pStatus
      case "cached"
         put URL pURL into field "Output"
         break
      case "error"
         answer "Error:" && libURLErrorData(pURL)
         break
      case "timeout"
         answer "Request timed out."
         break
   end switch
end myCallback

🟢 You can also check the response headers after a request using libURLLastHTTPHeaders() to see what you sent, and libURLLastRHHeaders() to see the server's response headers — useful for debugging unexpected responses.