SDK Design: The Contract's User Interface

The distance between client.request("POST", "/v1/payments", body) and payments.create(params) is not sugar — it is who holds the contract knowledge. With raw transport, every consumer re-derives paths, shapes, error meanings and retry rules from the docs, each with their own bugs; the contract is re-implemented N times. A real SDK is the contract *encoded once, by the people who wrote it*: typed methods per operation, typed models per resource, and — the part that matters most — the behavioral clauses turned into code.

The behavioral clauses are where SDKs earn their keep, because they are exactly what consumers get wrong alone (Documentation Is Part of the Contract can state them; the SDK can enforce them). Retries with exponential backoff and jitter, on retryable failures only, with an Idempotency Keys: The Mechanism key generated per logical operation and reused across attempts — safe retry-by-default instead of N hand-rolled retry loops, half of them double-charging. Pagination as an iterator, so "the first page is all the data" bugs become impossible (Pagination: Choosing How Lists End). Errors mapped from the wire taxonomy to typed exceptions consumers can branch on — CardExpiredError, not string-matching a message (An Error Taxonomy Clients Can Branch On). Timeouts with sane defaults, Request-Id surfaced on every error for support (Request IDs: The Contract's Correlation Clause), rate-limit headers translated into waiting (The Rate-Limit Contract).

Here is where SDK design joins this module: the SDK is a *compiled snapshot of the contract*, deployed into codebases you cannot touch, on upgrade cycles you do not control. Every forward-compatibility clause the API declares must be *implemented* in the SDK, or the clause is fiction. The contract says clients tolerate unknown response fields (Backward Compatibility: The Real Rules) — so generated models must preserve-and-ignore unknown keys, never throw on them, and strict-deserialization defaults in the target language must be explicitly disarmed. The contract says enums are extensible (Enum Evolution: The New Value That Broke Old Clients) — so generated enum types must decode unknown values into a usable representation (a raw-value case, a wrapper type) instead of crashing, which is precisely where naive codegen in strict languages fails first.

This is the quiet catch in Schema-First vs Code-First codegen: the generator's defaults decide whether your entire SDK fleet is forward-compatible, and most generators' defaults are strict. Audit the generated deserialization path per language against one test: *serve a response with three unknown fields and one unknown enum value; the SDK must succeed*. Run that test in CI against every SDK you ship (see Testing the Contract, Not Just the Code) — it is the mechanical form of the tolerant-reader clause, and it is what makes "adding a field is safe" true for your actual consumer base rather than your ideal one.

SDK versioning then has its own layer: semver over the *SDK surface*, which is correlated with but not identical to the API's compatibility rules. An additive API change is a minor SDK release; a breaking SDK change (renamed method, changed types) can exist without any API change at all — and because old SDK versions keep calling the current API for years, the API's deprecation windows must account for the SDK-upgrade lag, and old-but-supported SDKs must keep working against the evolving API for as long as their pinned behavior is served (Versioning: What a Version Even Promises's date-pinning interacts well here: the SDK version can pin the API behavior date it was built against).

An SDK is judged in the consumer's language, not yours. Async models must be native (promises in TypeScript, context in Go, asyncio-compatible in Python); naming follows the language's casing and conventions, mapped mechanically from the wire names; errors integrate with the language's idiom (exception hierarchies where those are native, error values where those are). This is why pure template-driven codegen plateaus at "technically usable": the common structure comes from the spec, but idiom needs per-language handwork — which is also the honest budgeting fact: every supported language is a product with its own tests, docs, release train and issue queue. Two excellent SDKs beat six abandoned ones; the languages you do not support get raw HTTP plus great docs, which is a legitimate tier, not a failure (Documentation Is Part of the Contract carries them).

Two design boundaries keep SDKs trustworthy. Thin over clever: the SDK encodes the contract — transport, auth plumbing, retries, types, pagination — and stops before business logic, client-side caching with invented semantics, or "helpful" validation that duplicates and then contradicts the server's (Validation Errors: Feedback, Not Verdicts is the server's job; a stricter SDK than server rejects valid requests, a looser one converts clean 422s into confusing successes-then-failures). Every clever behavior is contract surface you now maintain across all languages forever. Observable by default: hooks for logging and tracing, Request-Id on every error, and an SDK-version header on every request — that last one is Consumer-Driven Evolution: Telemetry Before Breakage's cheapest, highest-value input, shipped for free with every call.