21 guides across 6 sections, in JavaScript and TypeScript.
Authenticate and authorize calls
Get a valid credential onto every request and keep it valid: keys, tokens, OAuth and OIDC flows, signatures and mTLS, from both the client and the producer side.
Send API keys and bearer tokens
- Add a bearer token to fetch without a client library Wrap fetch in one function that sets Authorization for a single API origin, so no call site forgets the token and no redirect carries it to another host.
- Diagnose a 401 or a 403 from a credential Read the WWW-Authenticate challenge rather than the status code, so a client can tell the credential failures apart and take the action that fixes each.
- Keep test and live API keys from crossing environments Put the environment in the key itself and check it at process start, so a staging deployment holding a production credential refuses to run.
- Refresh an access token once under concurrent requests Hold the refresh in a single promise so concurrent callers await the same request, and a burst of expiries makes one call to the token endpoint.
Make calls that survive failure
Timeouts, retries, backoff, rate limits, idempotency, caching and error handling, on the client and server side of any API. These branches own the behavior; an SDK feature that implements it is one option here.
Set retries and timeouts
- Add a circuit breaker to an outbound HTTP client Stop calling a failing dependency, try one request after a cool-off, and close the circuit only if it succeeds, so an outage costs one timeout not thousands.
- Enforce one total deadline across all retry attempts Create the deadline once before the first attempt and compose it with each per-attempt timeout, so retries and their waits come out of one budget.
- Retry fetch calls with exponential backoff in Node.js Retry only the statuses the server meant as temporary, back off with full jitter, and honor Retry-After, so a shared outage does not become a stampede.
Handle and design API errors
- Return validation errors a client can map to a form Answer a bad request with an RFC 9457 problem document carrying one JSON Pointer entry per failing field, so a client can attach each message to an input.
Move data in and out
Reading collections page by page, streaming, bulk jobs, file transfer, loading API data into notebooks, and scheduled pipelines that keep a copy in sync.
Paginate collections
- Advertise next and previous pages with Link headers Send the next, previous, first and last page URLs in a Link header, so clients follow links you build rather than assembling query strings themselves.
- Choose a pagination style for a list endpoint Compare the four ways to page a list on what decides it: whether a caller can miss a row when the data shifts, and what the query costs at page 900.
- Encode and sign opaque pagination cursors Encode the page position as base64url JSON and sign it with HMAC, so callers carry a cursor without reading it and a tampered one never reaches your query.
- Negotiate page size between an API and its clients Clamp an over-large page size to your ceiling rather than rejecting it, say in the response what was served, and refuse only values that are not sizes.
Ship an SDK
Choosing how to produce client libraries, generating them, making them idiomatic, composing runtime features, customizing a generator without forking, adding languages, and regenerating safely.
Choose a generator and generate an SDK
- Generate your first SDK with sdkgen Scaffold a project from your OpenAPI document with one non-interactive command, generate a TypeScript SDK, and read what the model made of your endpoints.
Test and mock integrations
Mocks, record-and-replay, contract and spec-driven tests, and layered SDK test suites, for APIs you ship and APIs you do not own.
Mock an API
- Stub outbound HTTP calls in Node tests with nock Intercept outbound requests in-process, assert on what your code sent as well as received, and turn off real network access so an unstubbed call fails.
Run contract and spec tests
- Choose consumer-driven or spec-driven contract tests Pick a contract style by what it fails on: the fields one consumer reads, or everything the published document describes, including the unused parts.
- Contract test an API you do not own Write down the fields your integration reads, check a recorded response against them, and run the same check against the live API on a schedule.
- Validate responses against the OpenAPI document at runtime Build a validator from the response schema in your OpenAPI document and run it over real responses, so a service that stops matching its description fails.
Parse, validate and transform data
Reading the formats integrations depend on, building parsers from grammars, validating shapes at boundaries, and transforming nested data.
Parse config and data formats
- Accept comments and unquoted keys in a JSON config file Parse a hand-edited config with a lenient JSON dialect, so comments, trailing commas and unquoted keys load instead of failing on one character.
Validate data shapes
- Write a validator whose schema looks like the data Write the schema as an example of an accepted value, with constructors for types and literals for defaults, so schema and sample read side by side.
Transform nested data
- Merge nested config objects with predictable precedence Layer defaults, file, environment and flags with a deep merge so a later source overrides only the keys it sets, and clone first because merge mutates.
- Read a value at a nested path without null checks Read a deep value by a path held as a string, so a response mapper is a table of paths rather than a chain of optional accesses written out once per field.
Stop writing the same client twice#
Every guide here solves a problem a generated SDK already handles. Voxgig reads your OpenAPI description and generates the client, the CLI and the MCP server from one model.