v4

Client

View as markdown

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

A Synthient::Client holds a pool of keep-alive connections and is safe to share between threads. Create one, reuse it for every request, and call close on shutdown. In a forking server, connections inherited from the parent process are never reused.

new

Synthient::Client.new returns a client.

def initialize: (?api_key: String?, ?base_url: String, ?max_retries: Integer, ?timeout: Numeric,
                 ?open_timeout: Numeric, ?user_agent: String?, ?response_hook: _ResponseHook?) -> void

client = Synthient::Client.new(
  api_key: ENV.fetch("SYNTHIENT_API_KEY"),
  max_retries: 4,
  user_agent: "my-app/1.0"
)
at_exit { client.close }
  • Input: A missing or blank API key, a key or user_agent that contains a line break, or an invalid option raises ArgumentError. An api_key that is not a String, or a response_hook that does not respond to call, raises TypeError.
  • Network: It makes no network requests.

Options

  • Name
    api_key
    Type
    String?
    Description

    The API key. The default is the SYNTHIENT_API_KEY environment variable. Surrounding whitespace is trimmed.

  • Name
    base_url
    Type
    String
    Description

    The API base URL, including the version path. The default is Synthient::DEFAULT_BASE_URL. It must be an http or https URL with a host and no query, fragment, or user info. A trailing slash is removed.

  • Name
    max_retries
    Type
    Integer
    Description

    How many times a failed request is retried after the first attempt. The default is 2, and 0 disables retries. See Retries and timeouts.

  • Name
    timeout
    Type
    Numeric
    Description

    Seconds to wait for each read or write. The default is 60. It must be a positive, finite number.

  • Name
    open_timeout
    Type
    Numeric
    Description

    Seconds to wait for a connection. The default is 10. It must be a positive, finite number.

  • Name
    user_agent
    Type
    String?
    Description

    Appended, such as "my-app/1.2", to the User-Agent header, which starts with synthient-ruby/ followed by the SDK version.

  • Name
    response_hook
    Type
    _ResponseHook?
    Description

    Any object with a call method, such as a lambda, which receives a ResponseMetadata for every API response. See Response metadata.

close

Closes idle connections.

def close: () -> nil
  • Idempotence: It is idempotent.
  • Errors: Requests made after close raise IOError.

Constants

  • Name
    Synthient::DEFAULT_BASE_URL
    Type
    String
    Description

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

  • Name
    Synthient::VERSION
    Type
    String
    Description

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

  • Name
    Synthient::Client::MAX_BATCH_SIZE
    Type
    Integer
    Description

    1000, the most addresses lookup_ips accepts.

Response metadata

The response_hook: option is called with a ResponseMetadata for every API response, before its body is read.

interface _ResponseHook
  def call: (ResponseMetadata metadata) -> untyped
end

hook = lambda do |meta|
  rate_limit = meta.rate_limit
  puts "#{meta.status} #{meta.request_id} #{rate_limit.remaining}/#{rate_limit.limit}" if rate_limit
end
client = Synthient::Client.new(response_hook: hook)
client.account
  • Coverage: The hook sees retried attempts, export pages, stream handshakes, and responses that later fail to decode. Export downloads from storage are not reported.
  • Concurrency: The hook runs on the thread that sent the request, so a hook on a shared client must be thread-safe.
  • Errors: Exceptions the hook raises propagate to the caller.

ResponseMetadata

  • Name
    status
    Type
    Integer
    Description

    The HTTP status code of the response.

  • Name
    request_id
    Type
    String?
    Description

    The X-Request-Id header.

  • Name
    rate_limit
    Type
    RateLimit?
    Description

    The rate limit that applies to the operation, or nil unless all three RateLimit-* headers are present and valid.

  • Name
    headers
    Type
    Hash[String, String]
    Description

    A frozen copy of the response headers with lowercase names. 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. Limits are shared by every key of a team. See Rate Limits.

  • Name
    limit
    Type
    Integer
    Description

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

  • Name
    remaining
    Type
    Integer
    Description

    The number of requests left in the bucket.

  • Name
    reset
    Type
    Integer
    Description

    The number of seconds until the window resets.

Previous
Next