std.http

std.http is a client for talking to other services over HTTP and HTTPS. You can fetch data, send data, and interpret the response — including JSON — without building the request by hand.

The simple functions such as get_simple and post_simple cover the most common cases with the least setup, while the full variants let you control headers, query string and timeout in detail. Remember that the calls require the net.tcp capability — without it, nothing goes out on the network.

When to use it

Use std.http when your program needs to call an API. get and post make the call, response_status, response_text and response_json read the response, and json_get and json_post do both in one. Remember the net.tcp capability.

Getting started

bruk std.http som http

funksjon start() -> heiltall {
    la svar = http.get_simple("https://api.eksempel.no/tid", 5000)
    hvis http.response_ok(svar) {
        skriv(http.response_text(svar))
    } ellers {
        skriv("Feil: " + tekst(http.response_status(svar)))
    }
    returner 0
}

response_ok is true for status codes in the 200 range. Check it before you trust the response, and read the status code with response_status when something goes wrong.

The functions

Choose according to how much control you need. The simple functions (get_simple, post_simple, json_get_simple, json_post_simple) take only what is necessary. The full ones (get, post, json_get, json_post, request) let you set headers and query string. Either way you read the response with response_status, response_text, response_json and response_ok.

• request(metode: tekst, url: tekst, headers: ordbok_tekst, query: ordbok_tekst, body: tekst, timeout_ms: heltall) -> tekst — Makes a free HTTP call with full control over method, headers and body.
• request_full(metode: tekst, url: tekst, headers: ordbok_tekst, query: ordbok_tekst, body: tekst, timeout_ms: heltall) -> tekst — Like request, but returns the whole response including status and headers.
• response_status(response: tekst) -> heltall — The status code in the response (e.g. 200 or 404).
• response_text(response: tekst) -> tekst — The response body as text.
• response_json(response: tekst) -> ordbok_tekst — The response body interpreted as JSON (a map).
• response_header(response: tekst, nøkkel: tekst) -> tekst — The value of one header in the response.
• response_header_or(response: tekst, nøkkel: tekst, standard: tekst) -> tekst — A header value with a default if it is missing.
• response_ok(response: tekst) -> bool — True if the status code is in the 200 range.
• response_json_checked(response: tekst) -> ordbok_tekst — A JSON response that fails on an error status instead of pretending it is valid.
• request_simple(metode: tekst, url: tekst, body: tekst, timeout_ms: heltall) -> tekst — A simple call without your own headers or query string.
• request_full_simple(metode: tekst, url: tekst, body: tekst, timeout_ms: heltall) -> tekst — A simple call that returns the whole response.
• get(url: tekst, headers: ordbok_tekst, query: ordbok_tekst, timeout_ms: heltall) -> tekst — GET call with headers and query string.
• get_simple(url: tekst, timeout_ms: heltall) -> tekst — Simple GET call — just the URL and a timeout.
• post(url: tekst, body: tekst, headers: ordbok_tekst, query: ordbok_tekst, timeout_ms: heltall) -> tekst — POST call with body, headers and query string.
• post_simple(url: tekst, body: tekst, timeout_ms: heltall) -> tekst — Simple POST call with body and timeout.
• json_get(url: tekst, headers: ordbok_tekst, query: ordbok_tekst, timeout_ms: heltall) -> ordbok_tekst — GET call that interprets the response as JSON.
• json_get_simple(url: tekst, timeout_ms: heltall) -> ordbok_tekst — Simple GET call that returns JSON.
• json_post(url: tekst, body: ordbok_tekst, headers: ordbok_tekst, query: ordbok_tekst, timeout_ms: heltall) -> ordbok_tekst — POST call with a JSON body that returns a JSON response.
• json_post_simple(url: tekst, body: ordbok_tekst, timeout_ms: heltall) -> ordbok_tekst — Simple JSON POST.

Good to know

• All calls require net.tcp; without it, nothing goes out.
• Set a sensible timeout (timeout_ms) so a slow endpoint does not hang your program.
• response_json_checked returns an error on an error status instead of pretending the response is valid — useful when you want to fail early.

std.http is one of the modules in the standard library. Everything ships with the runtime — no installation, no external dependencies. See also Documentation for the language and the runtime.

Back to the overview