v4

Client

View as markdown

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

A Client is safe for concurrent use. Create one and reuse it for every request. It has no Close method.

NewClient

Returns a client that authenticates with apiKey.

func NewClient(apiKey string, opts ...Option) (*Client, error)

client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"),
	synthient.WithMaxRetries(4),
	synthient.WithUserAgent("my-app/1.0"),
)
if err != nil {
	log.Fatal(err)
}
  • Input: Surrounding whitespace is trimmed from the key, and an empty key returns ErrMissingAPIKey. An invalid option, such as a malformed base URL or a negative retry count, also returns an error.
  • Network: It performs no network I/O.

Options

  • Name
    WithBaseURL
    Type
    func(u string) Option
    Description

    Sets the API base URL, including the version path. The default is DefaultBaseURL. It must be an http or https URL with a host and no query or fragment.

  • Name
    WithHTTPClient
    Type
    func(hc *http.Client) Option
    Description

    Sets the HTTP client used to send requests. The client is copied and never modified. Don't set http.Client.Timeout on it, because that would also cut off streams and downloads; use context deadlines instead. The default client bounds the wait for response headers to one minute. Custom transports must not replay requests whose bodies cannot be rewound.

  • Name
    WithMaxRetries
    Type
    func(n int) Option
    Description

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

  • Name
    WithUserAgent
    Type
    func(s string) Option
    Description

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

  • Name
    WithResponseHook
    Type
    func(hook func(context.Context, ResponseMetadata)) Option
    Description

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

Constants and variables

  • Name
    DefaultBaseURL
    Type
    const string
    Description

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

  • Name
    Version
    Type
    const string
    Description

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

  • Name
    ErrMissingAPIKey
    Type
    error
    Description

    Returned by NewClient when the API key is empty or all whitespace.

Response metadata

WithResponseHook calls a function synchronously after each API response's headers arrive.

client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"),
	synthient.WithResponseHook(func(_ context.Context, meta synthient.ResponseMetadata) {
		if meta.RateLimit != nil {
			fmt.Println(meta.StatusCode, meta.RequestID, meta.RateLimit.Remaining, meta.RateLimit.Reset)
		}
	}),
)
if err != nil {
	log.Fatal(err)
}
  • Coverage: The hook sees retries, pages, stream handshakes, and decoding failures. Storage download responses are excluded.
  • Context: The context belongs to the caller's operation.
  • Concurrency: The hook must be safe for concurrent use, and it may retain or modify the metadata without affecting the client.
  • Disabling: A nil hook disables the callback.

ResponseMetadata

  • Name
    StatusCode
    Type
    int
    Description

    The HTTP status code of the response.

  • Name
    RequestID
    Type
    string
    Description

    The X-Request-ID header.

  • Name
    RateLimit
    Type
    *RateLimit
    Description

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

  • Name
    Header
    Type
    http.Header
    Description

    An independent 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. Limits are shared by every key of a team. See Rate Limits.

  • Name
    Limit
    Type
    int
    Description

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

  • Name
    Remaining
    Type
    int
    Description

    The number of requests left in the bucket.

  • Name
    Reset
    Type
    time.Duration
    Description

    How long until the bucket is full again.

Previous
Next