Designing an SDK on top of an HTTP API

Goal

Ship a client library that lets an integrator, human or agent, use the API without reading the HTTP details, without hiding the API's semantics, and without the SDK becoming a second API to maintain.

Prerequisites

A machine-readable API description (OpenAPI or protobuf) that is the single source of truth; a versioning policy for the API; a decision on which languages to support first, based on who integrates.

Steps

1. Generate the transport layer (models, serialisation, endpoint calls) from the description; never hand-maintain what the description already states. Keep generated code in its own package or directory so hand-written code survives regeneration.
2. Add one client object that owns configuration: base URL, credentials, timeouts, retry policy, a user agent carrying the SDK version. Read credentials from parameters first and environment variables second; do not invent configuration files.
3. Map HTTP errors to one exception or result type carrying status, the API's error body, the request id and whether the error is retryable. Do not throw different types per endpoint.
4. Implement retries once, in the transport: only for idempotent calls or calls carrying an idempotency key the SDK generates; exponential backoff with jitter; honour Retry-After; bound the total time.
5. Wrap pagination as an iterator that fetches pages on demand, and expose the raw page call for callers who need control.
6. Wrap long-running operations with a wait helper that polls using the server's hints and a deadline, returning the result or the operation's error.
7. Version the SDK independently of the API with semantic versioning; the SDK's major version changes when its own interface breaks, not when the API adds a field.
8. Test against a recorded or sandbox server in CI and against the live sandbox on a schedule; publish a changelog naming the API version each SDK release targets.
9. Write the README as the first-call tutorial: install, configure, one call, one error handled; link everything else to the API reference.

Expected result

Integrators write fewer lines and hit fewer retry and pagination bugs, and the SDK's behaviour matches the documented API semantics because most of it is generated.

Limits and test basis

A proposed protocol; no comparison between SDK designs is claimed. Hand-written conveniences (builders, helpers that combine several calls) are where SDKs drift from the API; keep them thin and label them as conveniences in the documentation.