Struct RequestBuilder 

pub struct RequestBuilder<'a> { /* private fields */ }

Fluent builder for a single HTTP request.

By default send returns Response even on non-2xx status. Use throw_on_error(true) to get Err from send, or use send_json which checks status before deserializing.

Implementations

impl<'a> RequestBuilder<'a>

pub fn param(self, key: impl Into<String>, value: impl ToString) -> Self

Sets a path template parameter (:key in the path).

pub fn params(self, params: HashMap<String, String>) -> Self

Merges path parameters from a map.

pub fn params_iter( self, params: impl IntoIterator<Item = (impl Into<String>, impl ToString)>, ) -> Self

Merges path parameters from an iterator.

pub fn query(self, key: impl Into<String>, value: impl ToString) -> Self

Adds a query string parameter.

pub fn queries(self, query: IndexMap<String, QueryValue>) -> Self

Sets multiple query parameters preserving insertion order.

pub fn query_json<T: Serialize>( self, key: impl Into<String>, value: &T, ) -> Result<Self>

Serializes value as JSON and uses it as a query parameter (feature json).

pub fn header( self, key: impl AsRef<str>, value: impl AsRef<str>, ) -> Result<Self>

Adds a request header.

pub fn json<T: Serialize>(self, body: &T) -> Result<Self>

Sets a JSON request body (feature json).

pub fn body(self, body: impl Into<Bytes>) -> Self

Sets a raw request body.

pub fn form<I, K, V>(self, fields: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<str>, V: AsRef<str>,

URL-encoded form body (application/x-www-form-urlencoded).

pub fn timeout(self, timeout: Duration) -> Self

Overrides the client default timeout for this request.

pub fn retry(self, policy: RetryPolicy) -> Self

Overrides the client default retry policy for this request.

pub fn auth(self, auth: Auth) -> Self

Overrides authentication for this request.

pub fn bearer_token(self, token: impl Into<String>) -> Self

Sets bearer authentication for this request.

pub fn cancellation_token(self, token: CancellationToken) -> Self

Cancels the in-flight request and retry sleeps when this token is triggered.

Examples

let client = Client::new("https://api.example.com")?;
let token = CancellationToken::new();
let token_clone = token.clone();
tokio::spawn(async move {
    tokio::time::sleep(Duration::from_millis(10)).await;
    token_clone.cancel();
});
let err = client
    .get("/slow")
    .cancellation_token(token)
    .send()
    .await
    .unwrap_err();
assert!(err.is_cancelled());

pub fn throw_on_error(self, throw: bool) -> Self

When true, send returns Err on non-2xx HTTP status (like upstream throw: true).

pub fn json_parser<F>(self, f: F) -> Self

where F: Fn(&Bytes) -> Result<Value, String> + Send + Sync + 'static,

Overrides the client’s JSON parser for this request only.

See crate::json_parser for fast path vs two-step parsing.

pub fn json_parser_fn(self, parser: JsonParserFn) -> Self

Overrides the client’s JSON parser for this request only.

pub async fn send(self) -> Result<Response>

Executes the request and returns the Response.

Non-2xx responses are returned as Ok(Response) unless throw_on_error is true. Deserialize JSON with Response::json or use send_json for a one-step typed result.

Examples

let client = Client::new("https://api.example.com")?;
let response = client.get("/users/1").send().await?;
if response.is_success() {
    println!("status {}", response.status());
}

pub async fn send_json<T: DeserializeOwned>(self) -> Result<T>

Executes the request and deserializes JSON on success (feature json).

Fails with Error::Http or Error::Deserialize on non-2xx or invalid JSON.

Examples

let client = Client::new("https://api.example.com")?;
let user: User = client.get("/users/:id").param("id", 1).send_json().await?;