---
title: "HTTP"
url: https://una-lang.org/en/docs/guides/http/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/una-for-agents.md
---

# HTTP

The host capability `Http` sends HTTP/1.1 requests (`spec/24`, edition 0.2).

- **Operations.** One per method, so `uses @http: Http[get]` can never post:
  - `get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response`;
  - `post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response`;
  - `put`, with the parameters of `post`;
  - `delete`, with the parameters of `get`.

  Each fails with `HttpError` and accepts `internal`. `Header` has `name: Text` and `value: internal Text`, and `Response` has `status: Int`, `headers: List[Header]` and `body: Text`.
- **Statuses are not failures.** A 404 is a `Response`. `HttpError` is for requests that got no response: `Denied`, `BadUrl`, `BadRequest`, `Unreachable`, `TimedOut`, `TooLarge`, `Tls` or `Protocol`.
- **Grants.** `http:<origin>` or `http:<origin>:<methods>`, by default `get`: `http:https://api.example.com:get,post`. A request outside them fails with `Denied`, before any connection. Plain `http` only where a grant says so.
- **Credentials.** `key_name: Some("name")` sends the key `name` of the run's `keys:` grant as `Authorization: Bearer <key>`, to that origin only. The program never sees it, and no trace shows it. An API that wants its token in another header, as `X-Api-Token`, takes it as a header value: a `secret` token needs a policy to `internal` first (§9).
- **Labels.** Arguments accept `internal` data: a `secret` URL, body or header value needs a policy first. Responses are `internal`, so a function that returns what it read declares an `internal` result, and its `Option` or `Result` too, since which one it returns depends on the response.
- **Failures are `internal`.** The server receives the URL, the headers with their values and the body, and may decide whether the request fails by them, so the failure of every request is `internal`, as its response is (S-15). Handle it with `attempt` and return a labeled value: `if error pass` or `if error fail` is U4002.
- **Header values.** A header value with a control character other than a tab, such as a newline, aborts the run with U6004, since the value is `internal`. Remove them from values built from data first: `value.replace(pattern: "\n", by: "")`.
- **Limits.** `--max-response <MiB>` (default 16) and `--http-timeout <seconds>` (default 30, the total time of a request). Tests give `Http` a handler, since examples cannot use it. As any handler, it implements every operation of the capability, all four (U3011), as `fixed_answer` below.

```una
module weather

--- The temperature of a city, from a JSON API, or `None` when the request or its answer fails.
--- The token is the key `weather` of the run's `keys:` grant; the program never sees it.
pub temperature(city: Text) -> internal Option[internal Int]
  uses @http: Http[get]
=
  let accept = Header(name: "Accept", value: "application/json")
  let r = attempt @http.get("https://api.example.com/v1/now?city={city}", headers: [accept], key_name: Some("weather"))
  when r
    is Ok(response) -> if response.status == 200 then degrees(response.body) else None
    is Err(e) -> None

--- The `degrees` field of a JSON object, when it is an integer.
degrees(body: internal Text) -> internal Option[internal Int]
=
  let doc = body.parse_json()
    if error use Null
  when doc
    is Object(fields) ->
      let value = fields.get(key: "degrees")
        if none use Null
      when value
        is Number(n) -> Some(n)
        else -> None
    else -> None
```

A test of a function that uses `Http` installs a stand-in with `given`. Its parameter is named `answer`, not `body`, since an operation's parameter of the same name would clash with it (U1002):

```una
module stand_in

--- The status of a GET, or `None` when the request gets no response.
pub status_of(url: Text) -> internal Option[internal Int]
  uses @http: Http[get]
=
  let r = attempt @http.get(url, headers: [], key_name: None)
  when r
    is Ok(response) -> Some(response.status)
    is Err(e) -> None

--- A stand-in for an API: every GET answers 200 with `answer`, and the other methods 405.
pub handler fixed_answer(answer: Text) for Http
  op get(url, headers, key_name) = Response(status: 200, headers: [], body: answer)
  op post(url, headers, body, key_name) = Response(status: 405, headers: [], body: "")
  op put(url, headers, body, key_name) = Response(status: 405, headers: [], body: "")
  op delete(url, headers, key_name) = Response(status: 405, headers: [], body: "")

example "the stand-in answers every GET"
  given @http = fixed_answer(answer: "ok")
  do status_of("https://api.example.com/v1/now")
  expect result == Some(200)
```
