---
topic: dev-practices
author: Crashtech Editorial
published: Nov 15, 2026 · read: 4 min
---

API vs SDK: Choosing a Contract, a Client Library, or Both

A practical comparison of HTTP API contracts and language SDKs, including generated types, retry semantics, dependencies, and ownership.

– –
A craftsperson chooses between a raw interface blueprint and a fitted toolkit of client adapters.
Conceptual illustration of an API contract and the language-specific tools built around it.

A public HTTP API and its SDK answer different questions. The API contract describes what a service accepts and returns; an SDK packages one implementation for a particular language. OpenAPI is one language-agnostic way to describe HTTP operations so people and tools can understand them without reading service source code. [1]

The Architectural Spectrum: Specification vs Implementation

The relationship between an API and an SDK mirrors the relationship between an interface and a concrete class:

[ Your Application Code ]
           |
           +-----------------------------------------+
           | (Option A: High Abstraction SDK)        | (Option B: Raw API Call)
           v                                         |
+------------------------------------+               |
|      Language-Specific SDK         |               |
|  - Request helpers and typed models (varies by SDK)      |
|  - Optional retry and transport configuration            |
|  - Versioned dependency and migration surface             |
+------------------------------------+               |
           |                                         |
           v                                         v
+-------------------------------------------------------------+
|                 Raw Network Boundary (API)                  |
|          HTTPS REST / GraphQL / gRPC Endpoints              |
+-------------------------------------------------------------+
DimensionRaw Web API (REST / gRPC)Language SDK (Software Development Kit)
What It IsSpecification & wire contractPackaged software library & tooling
Language DependencyLanguage-agnostic (Any language that speaks HTTP)Specific to target language runtime (Python, Go, Node.js)
Error HandlingHTTP status and response bodyA library may map responses to language-specific errors
Connection LifecycleCaller chooses and configures an HTTP clientSDK may provide a configured client or accept one from the caller
Type SafetyThe wire format does not itself provide compile-time typesGenerated or handwritten types can improve checks, but do not validate every runtime response
Dependency WeightZero external runtime dependenciesAdds transitive dependencies and package footprint

What an SDK may add under the hood

An SDK can wrap request construction and expose convenience helpers, but its behavior is product- and version-specific. Inspect the documentation for the library you plan to use:

1. Authentication and request signing

Some APIs use request-signing schemes; others use bearer tokens, cookies or different mechanisms. If a service requires signing, its SDK may implement that protocol, but the API’s authentication documentation is the authority. Do not assume every SDK signs requests or that every signature uses the same canonicalization rules.

2. Retries and idempotency

Retrying can improve resilience, but it can also repeat a non-idempotent operation or increase load during an outage. AWS documents versioned retry behavior for its SDKs, including configuration and retry modes; that is an example, not a universal SDK guarantee. Before relying on retries, check which errors and operations the selected client retries and whether it supports idempotency keys. [3]

A common capped-jitter policy can be expressed as:

t_`{sleep}` = random(0, min(M, B * 2^`{attempt}`))

Where $B$ is base backoff and $M$ is maximum retry ceiling. Randomization can reduce clients retrying in lockstep, but the policy still needs an attempt budget, deadline and clear handling for operations that cannot safely repeat.

3. Persistent Socket Connection Pooling

Connection reuse depends on the SDK’s HTTP transport, runtime and configuration. Some clients expose custom transports or connection options; others manage them internally. Measure the application’s real workload rather than assuming an SDK guarantees a particular handshake count or latency.

Generated clients still need maintenance

For a provider supporting several language clients, generation can reduce duplicated model and request code. It still leaves a release and compatibility surface to maintain:

[Versioned API description]
                     |
                     v
+-------------------------------------------------------------+
|              Stainless / OpenAPI Generator                  |
|  - Compiles Language-Specific AST Models                    |
|  - Enforces Idiomatic Naming (camelCase vs snake_case)      |
+-------------------------------------------------------------+
         |                 |                 |
         v                 v                 v
   [Python SDK]      [TypeScript SDK]    [Go SDK]

An OpenAPI document can drive generated clients, but it is not automatically the sole source of truth for every provider. Generated output still needs versioning, error mapping, transport configuration, documentation and compatibility review. Stripe’s Node library illustrates a maintained language-specific client with its own release and migration guidance. [1] [2]

Do

  • Prefer an official SDK when its supported runtime, release cadence, and documented behavior fit your integration; verify retries, timeouts and transport settings in the exact version you deploy.
  • Use an API description such as OpenAPI to generate client models or stubs when that improves consistency, then review generated code and compatibility as part of the release process.
  • Expose raw HTTP response objects in SDK methods so advanced users can inspect debug headers and rate limit counters.

Don't

  • Do not import massive monolithic SDKs into lightweight serverless functions where cold-start bundle size is constrained.
  • Avoid handwriting bespoke SDKs for internal APIs with high schema churn; generate client stubs from OpenAPI or Protobuf instead.
  • Never hardcode API keys inside SDK client instantiation files checked into public version control.

A useful decision is often not “API or SDK”: the API is the service contract, while the SDK is one client implementation. Choose the library when its documented, versioned behavior saves work without obscuring operational needs. Use direct HTTP when you need a smaller dependency surface, an unsupported language or a behavior the SDK does not expose—and keep the service contract and error semantics explicit either way. Related reading: HTTP API design and idempotency and a real SDK version migration.

Advertisement

Frequently asked questions

What is the primary difference between an API and an SDK?

An API is the contract exposed by a service. An SDK is a software library or toolkit that helps one language or environment call that API; it can add types and helpers, but its behavior depends on its documentation and version.

Why do companies provide language-specific SDKs instead of just publishing REST APIs?

An SDK can reduce repeated request construction and provide language-specific helpers or types. The exact features vary by provider and version, so developers should verify transport, authentication and retry behavior in its documentation.

What are the hidden maintenance costs of publishing official SDKs?

An SDK has its own releases, dependencies, compatibility promises, security updates and migration path. If a provider supports several language clients, each may have different features or release timing.

When should an engineering team integrate via raw HTTP API rather than an official SDK?

Direct HTTP can suit an unsupported runtime, a constrained dependency budget, or a request flow the library does not expose. The application then owns request construction, timeouts, errors and any safe retry behavior it needs.

Sources & further reading

/* Comments */