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 happened | variant | code |
|---|---|---|
| the request produced no answer | Error::Host | ACTION_FAILED |
| the service answered outside 2xx | Error::Domain | HTTP_STATUS_<status> |
| the answer did not fit the answer type | Error::Json | HTTP_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.