Steel API

Steel API client

This library provides convenient, typed access to the Steel API from Rust.

The full API of this library can be found in api.md.

Installation

cargo add steel-rs

Usage

use steel::Steel;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Steel::new(std::env::var("STEEL_API_KEY")?);
    let result = client.sessions().create(steel::SessionCreateParams::default()).await?;
    println!("{:?}", result);
    Ok(())
}

Authentication uses API key (steel-api-key). The client reads the key from the STEEL_API_KEY environment variable when one is not passed explicitly.

Pagination

List methods are paginated. The SDK fetches further pages automatically as you iterate.

use futures::StreamExt;

let stream = client.sessions().list(steel::SessionListParams::default()).await?.into_stream();
futures::pin_mut!(stream);
while let Some(item) = stream.next().await {
    println!("{:?}", item?);
}

Handling errors

Methods return Result<T, steel::Error>. Each HTTP status maps to its own Error variant (BadRequest, RateLimit, NotFound, …); call Error::status() to read the status code for any of them:

match client.some_resource().some_method().await {
    Ok(result) => println!("{:?}", result),
    Err(err) => match err.status() {
        Some(status) => eprintln!("api error (status {status}): {err}"),
        None => eprintln!("request failed: {err}"),
    },
}

Retries

Certain errors are automatically retried twice by default with a short exponential backoff. Connection errors, 408, 409, 429, and 5xx responses are retried.

// Configure the default for all requests:
let client = Steel::new(api_key).with_max_retries(0); // default is 2

// Or per-request:
client.some_resource().some_method().max_retries(5).await?;

Timeouts

Requests time out after 1 minute by default. Configure this with a timeout option:

use std::time::Duration;

let client = Steel::new(api_key).with_timeout(Duration::from_secs(20));

// Or per-request:
client.some_resource().some_method().timeout(Duration::from_secs(5)).await?;

Per-request options

Chain builder methods on a request to override behaviour for a single call:

client
    .some_resource()
    .some_method()
    .header("X-Custom", "value")
    .idempotency_key("my-key")
    .await?;

Use .with_response() to access the HTTP status and headers alongside the body.

Requirements

Rust 1.86 or later (2021 edition).
The Tokio async runtime: the examples use #[tokio::main], which needs tokio = { version = "1", features = ["macros", "rt-multi-thread"] } in your Cargo.toml.

API reference

See api.md for the full list of resources and methods.

Contributing

See CONTRIBUTING.md.

License

Released under the MIT license. See LICENSE.

steel-rs 0.1.3