Call a web API

What an HTTP mount reaches

Your deployment's operator pins each HTTP mount to one origin, such as https://api.example.com, and decides who may use it and which credential it sends. Your app gives each request a path under that origin, and reaches nothing else.

Holding the handle is the grant. It arrives in datumhue.args.http_mounts, under the name your app was given it by, from the command line or from the app that started yours (Permissions and capabilities). To see what your deployment offers and try one out:

$ datumhue http-mount list
$ datumhue http-mount describe weather-api
$ datumhue run --http-mount weather:weather-api app.lua

• http-mount list lists the deployment's HTTP mounts, and describe shows one mount's origin and, when the operator attached one, a description of its API, as far as the mount's rules let you see it.
• --http-mount weather:weather-api grants the mount weather-api to the app, as weather in datumhue.args.http_mounts.

Make a request

local bytes = datumhue.bytes
local api = datumhue.args.http_mounts.weather

local res = api:get("/forecast", { query = { city = "Oslo" } }):ready()
if res.status == 200 then
    print("Oslo: " .. res.body:json().temperature)
else
    print("The weather service answered " .. res.status)
end

local sent = api:post("/reports", {
    headers = { ["content-type"] = "application/json" },
    body = bytes.json({ city = "Oslo", temperature = 4 }),
}):ready()
print(sent.status)

• HttpMount:get starts the request at once and returns a Response. Response:ready waits for it (Waiting). HttpMount:post, put, patch, delete and head work the same way, and take the same options.
• An HTTP error status is an answer, not a failure: check Response.status. Only a request that never got an answer raises, at Response:ready.
• Response.body is Bytes, so decode it where you read it, with Bytes:json or Bytes:text. A request's body is Bytes too; datumhue.bytes.json turns a table into JSON.

What the deployment decides

Your app chooses the method, the path, the query, the body and most headers. The deployment owns the rest:

• The host and the connection. A request that sets Host, a framing header such as Transfer-Encoding, a Proxy- or Sec- header, a forwarding header such as X-Forwarded-For, or a method override raises at the call.
• The path. It stays under the mount: a . or .. segment, in any spelling, raises "invalid path" at Response:ready. An encoded slash inside one segment, such as group%2Fproject, is sent as you wrote it.
• Redirects. The service's redirects are followed only within the mount; one that leads elsewhere raises "redirect refused".
• Writing. When the operator lets you only read through a mount, get and head work, and post, put, patch and delete raise "access denied" at Response:ready.

Credentials stay with the deployment

Your app never sees the credential a mount sends. The deployment adds it to each request as the operator configured the mount: a key the operator keeps, or the signed-in person's own sign-in (Sign people in). So a package you publish carries no secret, and a person can use it only through the mounts they are allowed.

See also

• Permissions and capabilities
• Launch other apps, for passing a mount to an app you start.
• Open, pick and save files, for decoding Bytes.

Reference used on this page: datumhue.bytes datumhue.args HttpMount:get Response:ready Response.status Response.body Bytes:json HttpMount:post datumhue.bytes.json Bytes:text