Skip to main content

Module http

Module http 

Source
Expand description

Calling a service outside the platform.

One function does the work, and five name a method for you:

#[derive(Deserialize)]
struct Rate {
    usd: f64,
}

let rate: Rate = simple::http::get("https://api.example.com/rates/eur")?;

assert_eq!(rate.usd, 1.09);

§The answer is the body

A call answers with the response body, read into the type the call site asked for — the same bargain crate::graphql makes. A body the service sent as JSON is read as JSON; a body it sent as text is read as text, which is what an answer type of String receives; and a body with nothing in it reads as null, which is what () and Option<_> receive. The status decides whether there is an answer at all, and travels with the failure when there is not.

§Three outcomes, told apart at the call site

what happenedvariantcode
the request produced no answerError::HostACTION_FAILED
the service answered outside 2xxError::DomainHTTP_STATUS_<status>
the answer did not fit the answer typeError::JsonHTTP_RESPONSE_UNREADABLE

So a 404 and an unreachable host are two different things to an action, by the variant it matches on and by the code it reports, and the status a service refused on is carried in the code, the message and the details.

§What a failed call says about repeating it

A service that answers 4xx has refused the request, so the repair is the request. A service that answers 5xx, or that answers nothing at all, accepted the request and then failed — and what repeating it costs depends on the method, which is the same argument crate::graphql makes about a read and a write. A GET changes nothing and may simply be made again; a PUT or a DELETE may already have landed, and reaches the same state when it is sent twice; a POST or a PATCH may already have landed, and can apply twice. Each failure carries the sentence that fits it in its hint.

§Why get takes a URL and nothing else

Most calls carry no headers, so the five method functions take what that call needs and no more — a URL, and a body where the method has one. A call that does carry headers is a Request, which is a plain struct with a Default, so the fields it does not set are the ones it does not write:

use simpleplatform_sdk::http;

let leads: Vec<Value> = http::fetch(http::Request {
    url: "https://api.example.com/leads".to_string(),
    headers: http::headers(&[("Authorization", "Bearer T")]),
    ..http::Request::default()
})?;

assert!(leads.is_empty());

That is one shape rather than two: no empty map to build for the common call, no type parameter beyond the answer type, and no builder to learn — the struct literal already names every field it sets.

§Two requests, two names, one file

An action already has a Request: the one it was called with, which the prelude brings in. So an outbound request is written under the module it belongs to — http::Request — and both names stay available in the same file, each meaning one thing:

use simpleplatform_sdk::http;

#[derive(Deserialize)]
struct Input {
    lead_id: String,
}

fn handler(request: Request<Input>) -> Result<Value, Error> {
    http::fetch(http::Request {
        url: format!("https://api.example.com/leads/{}", request.data.lead_id),
        headers: http::headers(&[("Accept", "application/json")]),
        ..http::Request::default()
    })
}

let lead = handler(Request::new(Input { lead_id: "L1".to_string() }))?;

assert_eq!(lead["id"], json!("L1"));

Structs§

Request
One outbound request.

Enums§

Method
The method a request is made with.

Functions§

delete
Remove a resource.
fetch
Make a request and answer with its body.
get
Read a resource.
headers
The headers for a request, from the pairs that make them up.
patch
Change part of a resource.
post
Submit to a resource.
put
Replace a resource.