Crate api_req

Crate api_req 

Source
Expand description

Make API calls more easier!

In v0.3, the attribute in derive macros is changed to #[api_req(...)] instead of #[api(...)] and #[payload(...)].

In v0.5, we have better error spanned in proc-macro. And use array for headers instead of tuple. Add default_headers_env_value_or_omit attribute meta.

§Advantage

For example:

ⓘ
use api_req::Method;

#[derive(Debug, Default, Clone, Serialize, Payload)]
#[api_req(
    path = "/payments/{customer_id}", // format from struct fields
    method = Method::POST,
    ...
)]
pub struct ExamplePayload {
    #[serde(skip_serializing)]
    customer_id: String,
    amount: usize,
}

You can not only define the path, method, payload-format, pre-deserialize-action, and deserialize method, but also can format the path, headervalue with fields in the payload struct.

§feature

  • stream - support stream response: RespStream
  • cookies - store cookies, which can be retrieved from COOKIE_JAR

§Example

use api_req::{header, Payload, RedirectPolicy, ApiCaller, Method, ApiCaller as _};
use serde::{Serialize, Deserialize};
#[derive(Debug, Default, Clone, Serialize, Payload)]
#[api_req(
    path = "/payments/{customer_id}",
    method = Method::POST,
    headers = [(header::AUTHORIZATION, "Bearer token {bearer_token}")],
    req = form,  // use `form` to set body format instead of the default `json`
    before_deserialize = |text: String| text.strip_prefix("START: ").map(ToOwned::to_owned).ok_or(text),   // strip prefix, or original content if failed. `|String| -> Result<String, String>`
    deserialize = serde_urlencoded::from_str,   // deserialize with serde_urlencoded instead of the default serde_json
)]
pub struct ExamplePayload {
    #[serde(skip_serializing)]  // skip this field when serializing payload
    customer_id: String,
    #[serde(skip_serializing)]
    bearer_token: String,
    amount: usize,
}

#[derive(Debug, Deserialize)]
struct ExampleResponse {
    client_secret: String,
}

#[derive(ApiCaller)]
#[api_req(
    base_url = "http://example.com",
    default_headers = [(header::USER_AGENT, "...")],
    default_headers_env = [("api-key", "API_KEY")],    // get from env, panic if not presented
    default_headers_env_or_omit = [("bala", "BALABALA")],   // omit if not presented
    redirect = RedirectPolicy::none()   // set redirect policy
)]
struct ExampleApi;

let payload = ExamplePayload::default();
let _resp: ExampleResponse = ExampleApi::request(payload).await.unwrap();
// this will send a POST request to http://example.com/payments/{customer_id}
// with form `{"amount": 0}`

For POST request, the payload will be serialized as json body by default.

For GET request, the payload will be serialized as query parameters (urlencoded) by default.

You can set the payload format by req attribute in the #[api_req(...)] attribute, avaliable values are:

  • json
  • query
  • form
  • body (payload: Into<Body>)

One should ensure the req matches its Method.

Re-exports§

pub use api_caller::ApiCaller;
pub use api_caller::COOKIE_JAR;cookies
pub use payload::Payload;
pub use request::Request;
pub use request::RespStream;stream

Modules§

api_caller
Caller of the API
error
Error module
header
HTTP header types
payload
Payload
request
Request from ApiCaller and Payload, a future that can be awaited to get the response

Structs§

Body
An asynchronous request body.
Method
The Request Method (VERB)
RedirectPolicy
A type that controls the policy on how to handle the following of redirects.
RequestBuilder
A builder to construct the properties of a Request.

Traits§

CookieStorecookies
Actions for a persistent cookie store providing session support.
StreamExtstream
An extension trait for Streams that provides a variety of convenient combinator functions.

Derive Macros§

ApiCaller
Derive the Api trait
Payload
Derive the Api trait