Guide HTTP Client

HTTP Client

ARO provides HTTP client capabilities for making requests to external services and APIs.

Making HTTP Requests

Use the Request action to make HTTP requests. The preposition picks the default method, and a method: in the config object overrides it:

• from - GET request
• to - POST request
• with { method: "..." } - any method (PUT, DELETE, PATCH, ...)

GET Requests

Use from preposition to make GET requests:

(* Simple GET request *)
Create the <url> with "https://api.example.com/users".
Request the <users> from the <url>.

POST Requests

Use to preposition to make POST requests. A body that is a variable has to go in body: — a bare with <user-data> is read as the config object, so the request goes out with no body at all:

(* POST a record *)
Create the <user-data> with { name: "Alice", email: "alice@example.com" }.
Create the <api-url> with "https://api.example.com/users".
Request the <result> to the <api-url> with {
    body: <user-data>,
    headers: { "Content-Type": "application/json" }
}.

A map in body: is serialized to JSON. A string literal is the exception: with no config object around it, Request the <result> to the <api-url> with "name=Alice". sends that string as the body.

Other HTTP Methods

For PUT, DELETE, and PATCH, pass the method in the config object with with { method: "..." }:

(* PUT request *)
Request the <result> to the <url> with { method: "PUT", body: <update-data> }.

(* DELETE request *)
Request the <deletion> to the <url> with { method: "DELETE" }.

(* PATCH request *)
Request the <patched> to the <url> with { method: "PATCH", body: <partial-data> }.

The config method always overrides the preposition.

Response Handling

The Request action returns a response envelope with three fields. It parses JSON bodies automatically (objects become maps, arrays become lists, everything else stays a string). Pull fields off the response with Extract:

Field	Description
body	Parsed response body (JSON map/list, or string)
status	HTTP status code (e.g., 200, 404)
headers	Response headers as a map

Create the <api-url> with "https://api.example.com/users".
Request the <response> from the <api-url>.

(* Parsed body *)
Extract the <users> from the <response: body>.

(* Response metadata *)
Extract the <status> from the <response: status>.
Extract the <headers> from the <response: headers>.

Unknown keys fall through to the body, so Extract the <name> from the <response: name> reads a field off a JSON-object body directly.

Read the envelope with Extract, not with a qualifier in expression position: Log <response: status> to the <console>. fails with Cannot access property 'status' on AROHTTPResult. Bind the field first, then use the binding.

Complete Example

(* Fetch weather data from Open-Meteo API *)

(Application-Start: Weather Client) {
    Log "Fetching weather..." to the <console>.

    Create the <api-url> with "https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true".
    Request the <response> from the <api-url>.
    Extract the <weather> from the <response: body>.

    Log <weather> to the <console>.

    Return an <OK: status> for the <startup>.
}

Implementation Notes

• There are two client implementations in the runtime, and Request uses the URLSession-based one on both macOS and Linux (on Linux via FoundationNetworking) — it copes with the sync-to-async bridging a compiled binary does, where the NIO client can block on a semaphore. The SwiftNIO/AsyncHTTPClient client, AROHTTPClient, is what serves outbound OpenAPI callbacks.
• Compatible with both interpreter (aro run) and compiled binaries (aro build)
• Default timeout: 30 seconds; with { timeout: 60 } sets it, in seconds
• Automatically parses JSON responses
• Thread-safe for concurrent requests
• Windows has no HTTP client at all — a Request there fails with HTTP client is not available on this platform (#681). See the Platform Support table in the README for the full per-platform picture.

See Also

• I/O Services Specification - HTTP client specification
• Examples/HTTPClient - Working example