v4

Client

View as markdown

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

A SynthientClient is safe for concurrent use and pools connections. Create one and reuse it for the life of the application.

public sealed class SynthientClient : IDisposable

Constructors

The parameterless constructor reads the API key from the SYNTHIENT_API_KEY environment variable, and so do options whose ApiKey is null.

public SynthientClient()
public SynthientClient(string apiKey)
public SynthientClient(SynthientClientOptions options)

using var client = new SynthientClient(new SynthientClientOptions
{
    MaxRetries = 4,
    UserAgent = "my-app/1.0",
});
  • Input: Surrounding whitespace is trimmed from the key. A missing or empty key, a key with characters other than printable ASCII, or an invalid option throws an ArgumentException (an ArgumentOutOfRangeException for MaxRetries and Timeout).
  • Options: Options are copied, so changing them later has no effect on the client.
  • Network: No constructor performs network I/O.

SynthientClientOptions

  • Name
    ApiKey
    Type
    string?
    Description

    The API key. When null, the client reads the SYNTHIENT_API_KEY environment variable. Surrounding whitespace is removed.

  • Name
    BaseAddress
    Type
    Uri
    Description

    The API base address, including the version path. The default is SynthientClient.DefaultBaseAddress. It must be an absolute http or https URI with no user info, query, or fragment.

  • Name
    MaxRetries
    Type
    int
    Description

    How many times a failed request is retried. The default is 2, and 0 disables retries. It must not be negative. See Retries and timeouts.

  • Name
    Timeout
    Type
    TimeSpan
    Description

    How long the client waits on the network before throwing ApiTimeoutException. It bounds each wait for response headers and each read of a response body, stream, or download, not the length of a whole call, so long-lived streams and large downloads are not cut off. The default is 60 seconds, and Timeout.InfiniteTimeSpan disables it. Any other value must be positive and at most int.MaxValue milliseconds.

  • Name
    UserAgent
    Type
    string?
    Description

    A product token, such as "my-app/1.2", appended to the User-Agent header, which starts with synthient-dotnet/ followed by the SDK version. It must contain only printable ASCII characters.

  • Name
    ResponseHook
    Type
    Action<ResponseMetadata>?
    Description

    Called with the metadata of every response from the Synthient API. See Response metadata.

  • Name
    Handler
    Type
    HttpMessageHandler?
    Description

    The HTTP handler that sends requests, for custom proxies, certificates, or tests. The client never disposes it. It must not follow redirects, because a followed export redirect would send the API key to the storage host, so a SocketsHttpHandler or HttpClientHandler with AllowAutoRedirect set is rejected, even inside a DelegatingHandler. Both set it by default. The handler should not retry requests either: the client retries on its own, and a handler that resends a billed lookup can be charged twice. Set SocketsHttpHandler.MaxResponseDrainSize to 0 so that leaving a stream or download early closes its connection, as the client's own handler does.

Static members

  • Name
    SynthientClient.Version
    Type
    const string
    Description

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

  • Name
    SynthientClient.DefaultBaseAddress
    Type
    static Uri
    Description

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

Dispose

Releases the client's connections.

public void Dispose()
  • Errors: Calls made afterwards throw ObjectDisposedException, and calls still waiting for a response or for a retry are cancelled with an ObjectDisposedException.

Response metadata

SynthientClientOptions.ResponseHook is called synchronously with the metadata of every response from the Synthient API.

using var client = new SynthientClient(new SynthientClientOptions
{
    ResponseHook = metadata =>
    {
        if (metadata.RateLimit is not null)
        {
            Console.WriteLine($"{metadata.StatusCode} {metadata.RequestId} {metadata.RateLimit.Remaining} {metadata.RateLimit.Reset}");
        }
    },
});
  • Coverage: The hook is called for error responses, each retry, each page, stream connections, export redirects, and responses that fail to decode. It is not called for export downloads from storage.
  • Errors: If the hook throws, the call fails with its exception.
  • Concurrency: The hook must be safe to call concurrently. The metadata and its headers are read-only copies, so the hook can keep them.

ResponseMetadata

The constructor is public for tests. It copies headers and matches their names case-insensitively.

public sealed class ResponseMetadata
public ResponseMetadata(int statusCode, IReadOnlyDictionary<string, IReadOnlyList<string>> headers)
  • Name
    StatusCode
    Type
    int
    Description

    The HTTP status code.

  • Name
    RequestId
    Type
    string?
    Description

    The X-Request-Id header, or null if it is absent or empty.

  • Name
    RateLimit
    Type
    RateLimit?
    Description

    The rate limit state, or null if the response does not report it, as on CheckHealthAsync.

  • Name
    Headers
    Type
    IReadOnlyDictionary<string, IReadOnlyList<string>>
    Description

    The response and content headers, with case-insensitive names. Headers can contain sensitive data, such as presigned download URLs.

RateLimit

The rate limit state of the bucket a request was charged to, from the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. ResponseMetadata.RateLimit is null unless all three are present and valid. Buckets are shared by every key of a team. See Rate Limits.

public sealed record RateLimit(int Limit, int Remaining, TimeSpan Reset);
  • Name
    Limit
    Type
    int
    Description

    The bucket's burst size.

  • Name
    Remaining
    Type
    int
    Description

    The number of requests left in the bucket.

  • Name
    Reset
    Type
    TimeSpan
    Description

    How long until the bucket is full again.

Previous
Next