Call a service and interpret its response

Treat transport, HTTP status and JSON content as three different checks.

Choose the request API#

GetTextAsync is useful when you need successful response text. RequestAsync returns a JSON envelope containing status, headers and body, which lets your code inspect HTTP error responses as data. Transport failure still raises an exception. Use RequestWithCancellationAsync when the operation needs an explicit cancellation source.

Check the envelope before its body#

Inside an Async procedure with a declared url

Dim envelopeText As String
Dim envelope As JsonValue
Dim bodyText As String
Dim status As Long

envelopeText = Await Http.RequestAsync("GET", url, "{}", "", 10000)
envelope = Json.Parse(envelopeText)
status = CLng(Json.Value(Json.Get(envelope, "status")))
If status < 200 Or status >= 300 Then
    Err.Raise 513, "Search", "The service returned HTTP " & CStr(status)
End If
bodyText = CStr(Json.Value(Json.Get(envelope, "body")))

An HTML error page is not a successful JSON document. Checking status first makes the failure understandable and avoids presenting a JSON parsing error as the primary problem.

Validate the shape you use#

Parse the body, confirm optional object members with Json.Has and check array length before Json.At. Json.Value extracts a scalar, not an arbitrary nested object. A missing field and a JSON null are different conditions. Keep the previous valid UI state until the new response is usable.

Respect the request boundary#

The current request implementation accepts GET, POST, PUT, PATCH and DELETE, with an absolute HTTP(S) URL and a timeout from 1 to 30,000 milliseconds. Headers are a JSON object of strings; do not supply Host or Content-Length. Nonempty request bodies must be valid JSON. These limits belong to this implementation, not to HTTP in general.

Make remote calls deliberate#

A request sends the supplied URL, headers and body to the chosen service. Do not put credentials in tutorial source or logs. Use an endpoint you are authorized to call, follow its usage policy and use proper URL encoding for arbitrary user text. The simple space replacement in some bundled samples is not a general URL encoder.

Build and test the boundary#

Start with the service workbench for deterministic local JSON and settings. Then follow LibraryDesk or WeatherDesk, including the documented service limitations. Use the download lab when your result is a file instead of a JSON document.

Source baseline 20f4bfed6b · Build manifest