v4

Client

View as markdown

Create and configure the client, and read the metadata of every API response.

A Client is cheap to clone, and clones share one connection pool. Create one and reuse it for every request. Every future and stream it returns is Send. It has no close method, and its Debug output never includes the API key.

new

Returns a client that authenticates with api_key and uses the default configuration.

pub fn new(api_key: impl Into<String>) -> Result<Self>
  • Input: Surrounding whitespace is trimmed from the key. An empty key, or one with characters that are not allowed in an HTTP header, returns Error::InvalidInput. The SDK never reads the API key from the environment. Pass it explicitly, as Getting started does with SYNTHIENT_API_KEY.
  • Errors: Error::Http is returned if the TLS backend cannot be initialized.
  • Network: It performs no network I/O.

builder

Returns a ClientBuilder for a client that authenticates with api_key.

pub fn builder(api_key: impl Into<String>) -> ClientBuilder

use std::time::Duration;

use synthient::Client;

let client = Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .max_retries(4)
    .timeout(Duration::from_secs(30))
    .user_agent("my-app/1.0")
    .build()?;
let account = client.account().await?;
println!("{} credits left", account.lookup_quota.credits);
  • Use: Call its methods to change the configuration, then build.

ClientBuilder

pub fn base_url(self, url: impl Into<String>) -> Self
pub fn max_retries(self, retries: u32) -> Self
pub fn timeout(self, timeout: Duration) -> Self
pub fn user_agent(self, product: impl Into<String>) -> Self
pub fn http_client(self, builder: reqwest::ClientBuilder) -> Self
pub fn on_response(self, hook: impl Fn(&ResponseMetadata) + Send + Sync + 'static) -> Self
pub fn build(self) -> Result<Client>
  • Name
    base_url
    Description

    Sets the API base URL, including the version path. The default is DEFAULT_BASE_URL. It must be an http or https URL with a host and no credentials, query, or fragment. Trailing slashes are removed.

  • Name
    max_retries
    Description

    Sets how many times a failed request is retried. The default is 2, and 0 disables retries. See Retries and timeouts.

  • Name
    timeout
    Description

    Sets a time limit for each operation, covering every attempt and the waits between them. For streams and downloads, it covers opening them but not reading their bodies. There is no limit by default. An operation that runs out of time returns Error::Timeout.

  • Name
    user_agent
    Description

    Appends a product token, such as my-app/1.2, to the User-Agent header, which starts with synthient-rust/ followed by the crate version.

  • Name
    http_client
    Description

    Builds the HTTP client from a reqwest::ClientBuilder, for settings such as proxies, TLS roots, and connection timeouts. The SDK turns off its redirects, so the API key never reaches the storage host, and its retries, so billed lookups are never resent. Don't set a total timeout on it, because that would also cut off streams and downloads; use a read timeout instead. The default client gives up connecting after 30 seconds and fails a read that stalls for 60 seconds. A builder passed here replaces those defaults.

  • Name
    on_response
    Description

    Calls hook after each API response's headers arrive. See Response metadata.

  • Name
    build
    Description

    Builds the client. It performs no network I/O. Returns Error::InvalidInput if the API key is empty or contains characters not allowed in a header, or if the base URL or User-Agent is invalid, and Error::Http if the HTTP client cannot be built.

Constants

  • Name
    DEFAULT_BASE_URL
    Type
    &str
    Description

    "https://api.synthient.com/api/v4", the base URL of the Synthient HTTP API.

  • Name
    VERSION
    Type
    &str
    Description

    The version of the crate, such as "1.0.0". It is sent in the User-Agent header.

Response metadata

ClientBuilder::on_response calls a function synchronously after each API response's headers arrive.

use synthient::Client;

let client = Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .on_response(|meta| {
        if let Some(rate_limit) = &meta.rate_limit {
            println!(
                "{} {:?} {} {:?}",
                meta.status, meta.request_id, rate_limit.remaining, rate_limit.reset
            );
        }
    })
    .build()?;
let account = client.account().await?;
println!("{}", account.email);
  • Coverage: The hook sees retries, pages, stream handshakes, and error responses, but not download responses from the storage host.
  • Concurrency: The hook must be Send + Sync + 'static.
  • Lifetime: It receives a reference, so clone the ResponseMetadata to keep it.

ResponseMetadata

  • Name
    status
    Type
    StatusCode
    Description

    The HTTP status of the response.

  • Name
    request_id
    Type
    Option<String>
    Description

    The X-Request-ID header, which identifies the request when contacting Synthient support.

  • Name
    rate_limit
    Type
    Option<RateLimit>
    Description

    The rate limit that applies to the operation, or None if the response does not report one, as on health.

  • Name
    headers
    Type
    HeaderMap
    Description

    A copy of the response headers. Headers can contain sensitive data, such as presigned download URLs.

RateLimit

The state of an operation's rate limit, from the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. It is present only when all three headers hold non-negative integers. Limits are shared by every key of a team. See Rate Limits.

  • Name
    limit
    Type
    u64
    Description

    The bucket size, which is the burst the operation allows.

  • Name
    remaining
    Type
    u64
    Description

    The number of requests left in the bucket.

  • Name
    reset
    Type
    Duration
    Description

    How long until the bucket is full again.

Previous
Next