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.
313 guides in 17 sections, with code in bash, Go, Java, JavaScript, PHP, Python, Ruby, Rust, TypeScript and YAML. Each section splits into topics, and each topic holds the guides.
Section 1
Authenticate and authorize calls
13 guides in 4 topics
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 8
- Run OAuth 2.1 and OIDC flows 3
- Design an authentication scheme for your API 1
- Sign requests and use mTLS 1
Send API keys and bearer tokens 8 guides
Static credentials and short-lived tokens on plain HTTP from the client side: header versus query placement, key rotation without dropped requests, per-environment keys, token refresh without a race, scoping to least privilege, detecting leaked keys.
Add an API key with Guzzle middleware in PHP
Add an X-API-Key header to every Guzzle request for one API origin with a `mapRequest` middleware, keep it off redirects to other hosts, and test it offline.
Call a keyed API from a browser without shipping the key
Put the provider's key on a route you control, refuse that route to other sites, and search the bundle for the secret before every release.
Catch a leaked API key before it reaches the repository
Layer a gitleaks hook, GitHub push protection, a TruffleHog scan in CI, and a Thinkst canary key, then plant a key to prove which layer catches it and when.
Choose between header and query placement for an API key
Pick where an API key travels, header, query string, or cookie, by sending each form through a logging proxy and reading back which records keep the key.
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 callers that all see an expired token make one call to the token endpoint.
Run OAuth 2.1 and OIDC flows 3 guides
Choosing and implementing the flow from the client side: authorization code with PKCE, client credentials, device code, refresh-token rotation, token introspection, OIDC discovery, and why the implicit and password grants are gone.
Get a client credentials token for calls between services
Get a machine token with grant_type=client_credentials, name the API by audience or scope, cache it until it nears expiry, and prove it by counting token requests.
Run authorization code with PKCE in a single-page app
Log a user into a browser-only app with PKCE, keep the tokens in memory, renew them silently after a reload, and prove nothing is ever written to local storage.
Run the client credentials flow inside a generated SDK
Make the generated client fetch and renew its own machine token, through a generator setting or a feature you write, and prove that one token serves many calls.
Design an authentication scheme for your API 1 guide
The producer side: API keys versus OAuth 2.1 versus OIDC, scope design that limits blast radius without blocking common tasks, key formats and prefixes for secret scanning, token lifetimes, revocation, service accounts, per-customer keys, and the resource-server rules that let MCP clients and agents authenticate.
Enforce scopes at the resource server, not in the client
Turn the scope table in your OpenAPI document into checks on every request, prove them with a negative test suite, and answer refusals as 403 problems.
Sign requests and use mTLS 1 guide
Proving who sent the request: HMAC signatures in the AWS SigV4 style, HTTP Message Signatures (RFC 9421), JWT client assertions, and mutual TLS with certificate rotation, on both sides.
Authenticate to the token endpoint with a client assertion
Build a short-lived, single-use JWT, sign it with the client's private key, post it as client_assertion in place of a secret, and watch a reused one be refused.
Section 2
Make calls that survive failure
21 guides in 5 topics
Timeouts, retries, backoff, rate limits, idempotency, caching and error handling, on the client and server side of any API.
- Set retries and timeouts 5
- Set and respect rate limits 3
- Make writes safe to retry 1
- Cache API responses 4
- Handle and design API errors 8
Set retries and timeouts 5 guides
Deadline and retry policy for outbound calls: connect versus read timeouts, exponential backoff with jitter, retry budgets, which status codes and transport errors are retryable, retrying streaming and non-idempotent calls, circuit breakers, and adding the behavior to an SDK you ship.
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 a streaming response without replaying received data
Resume a stream that dies mid-body from the last event id or byte offset, stop on an explicit end, and refuse to retry a stream that carries no ids.
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.
Time out fetch calls with AbortSignal in Node.js
Put a hard deadline on every fetch call with AbortSignal.timeout, merge it with a caller's own signal, and tell a deadline apart from a cancellation.
Set and respect rate limits 3 guides
Both sides of a quota: publishing RateLimit header fields (IETF draft) and Retry-After, 429 versus 503, per-key and per-tenant limits, burst allowances; and on the client, reading the headers, client-side token buckets, shared limiters in Redis for many workers, concurrency limits, queueing for bursty agent traffic.
Choose between 429 and 503 when you throttle a request
Return 429 when one caller has spent its quota and 503 when the server is out of capacity, each with Retry-After and a body that names the policy.
Rate limit by API key and tenant, not client IP
Enforce one limit per API key and a larger one per tenant, so a noisy key cannot spend a customer's whole allowance and one customer cannot spend yours.
Read RateLimit headers and slow down before you get a 429
Read the remaining quota and the reset time from each successful response and space the requests so the window runs out as it ends, with no 429 halfway through.
Make writes safe to retry 1 guide
Making a retried write safe on both sides: the Idempotency-Key header (IETF draft), key generation and storage, fingerprinting request bodies, server-side replay windows, conflicts on mismatched payloads, and at-least-once delivery semantics.
Make queue consumer writes safe under redelivery
Derive an idempotency key from the message rather than from the attempt, so a broker that delivers at least once cannot charge a customer twice.
Cache API responses 4 guides
Client and server caching: ETag and If-None-Match, Cache-Control, stale-while-revalidate, TTL caches, cache keys that include auth, invalidation on write, CDN caching of API responses.
Build cache keys that include the caller and Vary headers
Stop a shared cache serving one tenant's response to another: key on the caller, the negotiated representation, and the query parameters that matter.
Choose Cache-Control values for private and shared caches
Give every class of endpoint one Cache-Control value from RFC 9111, check that each route sends it, and count the origin requests a shared cache makes.
Serve stale API responses and revalidate in the background
Add stale-while-revalidate and stale-if-error to a read endpoint so a shared cache hides origin latency and short outages, inside a window that ends.
Share an API response cache across many workers with Redis
Move a per-process response cache into Redis so forty workers pay one miss per key, with a lock on the miss and a policy that keeps cookies out of the shared store.
Handle and design API errors 8 guides
Errors a client and an agent can act on, from both sides: RFC 9457 problem details, stable error codes, field-level validation errors, retryable versus terminal taxonomies, partial failures in batches, mapping HTTP status to typed errors per language, and fail-safe semantics for autonomous callers (no vague 500s, 429 always with Retry-After).
Design an exception hierarchy for a PHP API client
Give a PHP API client one marker interface and a small exception tree, so callers catch everything from your package in one clause, or one failure class at a time.
Design error responses an autonomous agent can act on
Give an LLM caller a stable code, the parameter at fault, a next step, and a structured delay, so it fixes, waits, or stops instead of retrying a 500 forever.
Evolve an error contract without breaking clients
Add codes, retire codes and reword messages while clients in production keep working, with a catalog diff that fails the build on the changes that break them.
Model API errors in Rust with thiserror and Result
Give a Rust API client one error enum with a variant per failure class, derived with thiserror and returned from every method, so callers match on what went wrong.
Report partial failure in a batch endpoint
Return one outcome per item when a batch of writes half succeeds, name each failed item by the id the client sent, and never answer 200 when nothing was written.
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.
Translate upstream API errors behind your own API
Decide what your API returns when a provider it depends on fails, without leaking the provider's status codes, messages, or credential problems to callers.
Verify every error response matches one schema
Prove that no endpoint can return an error body outside your problem schema, using a lint over the description and a runtime check against the running service.
Section 3
Move data in and out
18 guides in 4 topics
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 9
- Stream responses and subscriptions 3
- Run bulk jobs and move files 4
- Load API data into notebooks and DataFrames 2
Paginate collections 9 guides
Cursor versus offset versus keyset versus Link header (RFC 8288) pagination, on both sides: designing a list endpoint that survives inserts and deletes, page-size negotiation, stable ordering, total counts, backwards paging; and on the client, auto-pagination iterators, parallel page fetching with backpressure, paging over GraphQL connections.
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.
Describe pagination so generators can follow it
Put enough in the OpenAPI document that a generated client can walk a collection by itself, instead of handing every consumer a single-page call.
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.
Loop over every page of a REST collection
Walk a paginated list endpoint to the end, read the three stop signals APIs actually send, and refuse to loop forever when a server repeats its cursor.
Migrate an API from offset to cursor pagination
Move a list endpoint from offset to cursor pagination without breaking the clients still sending an offset, and show why the change is worth making.
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.
Paginate an API with a Ruby enumerator
Wrap a paged list in an Enumerator that fetches pages as rows are pulled, so first(50) stays cheap, lazy.select stops early, and a 503 surfaces where you iterate.
Paginate an API with PHP generators
Walk a paginated collection with a generator, so a caller writes one foreach, pages are fetched only as they are consumed, and an early break costs nothing.
Stream responses and subscriptions 3 guides
Server-Sent Events, WebSockets, chunked and NDJSON responses, long polling, resumable streams with last-event ids, backpressure, reconnection, and streaming LLM tokens to a client, from both the producer and consumer side.
Add backpressure to a WebSocket consumer
Keep a slow sink from being overrun by a fast WebSocket feed: pause the socket in Node, read a WebSocketStream where it exists, or window acknowledgements.
Consume Server-Sent Events with fetch and custom headers
Read an SSE endpoint that needs a bearer token or a POST body, which EventSource cannot send, and own reconnection, the retry field and Last-Event-ID yourself.
Pick SSE, WebSockets, or long polling for a live endpoint
Serve one job-progress feed as SSE, WebSocket, long poll, and short poll, restart the proxy in front of it, and choose by what survives and what each event costs.
Run bulk jobs and move files 4 guides
Bulk import and export, batch endpoints, async jobs with status polling, multipart and resumable uploads (tus, S3 multipart), presigned URLs, and large downloads.
Batch writes without losing per-item error detail
Answer a batch write with one result per input, keyed by the client's id, under an errors flag, so a client retries only what did not land.
Import a CSV file through a bulk ingest job from a script
Normalize an exported CSV, run it through a Bulk API 2.0 ingest job, then download the failed and unprocessed rows and prove every row has exactly one result.
Poll a job status endpoint with backoff
Poll a job until it reaches a terminal state: honor Retry-After, back off with jitter when the server sends none, and stop at a deadline with the job id in hand.
Upload a large file with resumable chunks
Resume an upload from the last byte the server confirmed after a dropped connection or a closed tab, with tus, S3 multipart, Google resumable uploads, or your own.
Load API data into notebooks and DataFrames 2 guides
For analysts: paginated endpoints into pandas and Polars DataFrames, DuckDB httpfs and JSON functions over API responses, caching responses on disk while exploring, rate limits inside a notebook, flattening nested JSON into columns (pandas.json_normalize, jq, struct), Observable and Deno notebooks for JavaScript.
Load API data into Observable Framework with a data loader
Write a data loader that fetches a paginated API under Node at build time with a key from the environment, and read its JSON on the page with FileAttachment.
Ship a DataFrame-first Python client for your analysts
Generate a package where one call drains a paginated endpoint into a typed pandas frame, against a helper over `openapi-python-client` and a dlt source.
Section 4
Integrate beyond REST
11 guides in 4 topics
GraphQL, gRPC and protobuf, webhooks, and event streams, alongside or instead of REST, from both the producer and consumer side.
- Integrate with GraphQL 2
- Integrate with gRPC and protobuf 1
- Receive and send webhooks 6
- Consume and publish events 2
Integrate with GraphQL 2 guides
Consuming and exposing GraphQL: typed clients (graphql-codegen, Apollo, urql, graphql-request, gqlgen, Ariadne, Strawberry), persisted queries, connections pagination, batching and the N+1 problem, federation, REST-to-GraphQL gateways, and when to add a GraphQL layer at all.
Implement Relay connections in a GraphQL schema
Build the edges, cursors, and pageInfo a Relay-style connection promises, and get the page flags right rather than guessing them.
Retire a GraphQL field without versioning the schema
Deprecate the field with a reason naming its replacement, count per-client usage over a release cycle, and let a CI gate hold the removal until the window passes.
Integrate with gRPC and protobuf 1 guide
Protobuf IDL, buf and protoc codegen, gRPC-Web and Connect, grpc-gateway REST transcoding, streaming RPCs, deadlines and metadata, buf breaking for .proto versioning.
Define a gRPC service in a proto3 file
Write a proto3 file with a versioned package, two messages, a unary service, and reserved numbers, then compile it with buf and lint it two ways.
Receive and send webhooks 6 guides
Both sides of a webhook: signature verification (Standard Webhooks, Stripe, GitHub, Slack), replay protection, queue-first ingestion, idempotent handlers, retries with backoff and dead-letter queues, ordering, fan-out, describing webhooks in OpenAPI 3.1, local tunnels (ngrok, cloudflared), and testing (Svix Play, Hookdeck, recorded payloads).
Acknowledge a webhook fast and process it from a queue
Verify the signature, commit the delivery to durable storage, answer 200, and leave the slow work to a worker, so a sender's timeout cannot multiply one event.
Build a queue-backed webhook sender on BullMQ
Record each event and one delivery per endpoint, queue a BullMQ job per delivery, and let workers POST with a timeout and log every attempt, one queue per endpoint.
Expose a local webhook receiver with a tunnel
Get real deliveries from Stripe, GitHub, or Slack into a handler on localhost through a tunnel or a provider's forwarder, and what breaks when its URL changes.
Handle webhooks that arrive out of order
Reach the sender's current state when an update beats its create and a retry lands days late: fetch the object, compare a version, or serialize per object.
Validate a webhook payload's shape before handling it
Check that a verified delivery carries the fields your handler reads, with Zod, Ajv, or shape, and park a failing delivery instead of letting the sender retry it.
Verify a Standard Webhooks signature in PHP
Check the signature, the timestamp and the raw body of an incoming webhook in PHP, and keep two secrets valid so a rotation costs nobody a delivery.
Consume and publish events 2 guides
Event-driven integration: AsyncAPI descriptions, Kafka, NATS, SQS and SNS, CloudEvents, the outbox pattern, consumer groups, schema registries, at-least-once versus exactly-once.
Describe a Kafka topic with AsyncAPI
Describe one Kafka topic in AsyncAPI 3.0, from the SASL server to the keyed message, then validate it, lint it and pin which way each application faces.
Evolve an Avro event schema without breaking consumers
Register an Avro schema for a topic, set BACKWARD compatibility, and ship a field with a default that consumers you have not redeployed keep reading.
Section 5
Describe your API
23 guides in 7 topics
Authoring, linting, modelling and versioning the description that SDKs, docs and agent surfaces are generated from, including letting a coding agent draft or repair it.
- Write an OpenAPI description 7
- Author or repair a spec with a coding agent 3
- Lint and govern API specs 3
- Model resources, relations and actions 5
- Extract a semantic model from a spec 2
- Describe an API without OpenAPI 1
- Version and retire APIs 2
Write an OpenAPI description 7 guides
Writing OpenAPI 3.1 that tools can use: operationIds (snake_case, unique, verb plus noun, chosen to generate clean SDK method names), tags, components and $ref reuse, discriminators, nullable versus unions, examples, security schemes, servers, webhooks and callbacks, uploads, bundling and splitting, Swagger 2 to 3.1 migration, design-first versus code-first (FastAPI, NestJS Swagger, springdoc, swag, zod-openapi, Huma, tsoa).
Model a polymorphic response with a discriminator
Describe a response that comes in several shapes so a generator emits a tagged union rather than a bag of optional fields, using oneOf with a discriminator.
Organize operations with tags that docs and SDKs respect
Give every operation one declared, described tag in reading order, audit the list in CI, and measure what a tag rename moves in a tag-driven generator and in sdkgen.
Publish an OpenAPI 3.0 copy beside your 3.1 document
Keep OpenAPI 3.1 as the source of truth and build a 3.0 copy for older generators, with a guard that fails when the conversion loses or mangles anything.
Reuse schemas and responses with components and $ref
Move every repeated schema, parameter, and response under components and reference it with $ref, so generators emit one named type instead of a copy per use.
Set style and explode on array and object query parameters
Set style and explode on each array and object query parameter, serialize from the document in the client, and validate requests with a Prism mock.
Split and bundle a large OpenAPI document
Break a multi-thousand-line description into per-resource files, then produce the single bundled document most generators expect, without losing component names.
Write operationIds that generate clean SDK method names
Name every operation with a unique lowercase verb-plus-noun id, audit the ids in CI, rename the bad ones with an overlay, and diff the methods two generators make.
Author or repair a spec with a coding agent 3 guides
The spec as an output of AI, not only an input: drafting an OpenAPI description with Claude Code, Cursor or Copilot from route handlers, from HAR captures, from prose docs or a Postman collection; filling missing schemas and examples; repairing a spec that a generator rejects; validating the result with Spectral, Schemathesis and a mock server; keeping the agent-written spec in sync with code in CI.
Fill missing schemas and examples with a coding agent
List every response with no schema or example with two Spectral rules, hand the gaps and fixtures to a coding agent, and validate every example after every batch.
Set up a Spectral lint loop for an agent editing OpenAPI
Run Spectral on every OpenAPI edit a coding agent makes, through a Claude Code hook or a Cursor or Copilot instruction, so the agent fixes errors before moving on.
Turn a Postman collection into OpenAPI with a coding agent
Convert a Postman v2.1 export for a baseline, give a coding agent the gaps and saved examples, and check for invented required fields and a lossless round trip.
Lint and govern API specs 3 guides
Style rules and governance: Spectral rulesets and custom functions, Redocly lint, Stoplight style guides, vacuum, CI gates, checks that generated SDKs will be usable (every operation has an id, every response has a schema), conventions across many services.
Enforce a naming convention across 40 microservice specs
Run one naming ruleset in every repository, then compare terms across specs, because no per-document linter sees that billing says customer and CRM says client.
Gate a pull request on OpenAPI lint results
Make Spectral a required check that fails on errors and annotates warnings, and lint the whole document so an edit to a shared component cannot merge unseen.
Vet an aontu model for contradictions before you generate
Run aontu vet over every environment overlay in CI, so two files that disagree fail in seconds with both lines named, and refuse a release that rests on defaults.
Model resources, relations and actions 5 guides
Designing the resource model before or beside the spec: resource naming, id formats, sub-resources versus links, non-CRUD actions such as cancel or approve, filtering and sorting, field selection, relationships, deciding when an endpoint is an entity operation and when it is a standalone action.
Add field selection to resource responses
Add a fields parameter that returns a subset on request and the full object otherwise, refuse unknown names with an RFC 9457 problem, and check the mock agrees.
Decide if an endpoint is an entity operation or an action
Apply one test to every proposed endpoint, tabulate the verdicts, and catch the PATCH that refunds a card and sends an email while looking like a safe update.
Decide when a list filter should become a search endpoint
Triage requested queries into filters and searches, measure how long the search index trails a write, and keep an SDK list method off the search endpoint.
Design one filter and sort vocabulary for all resources
One filter and sort grammar for every list endpoint: a shared parser, a field declaration per resource, OpenAPI parameter components, and a CI check for drift.
Write a resource inventory before you write the spec
List every resource, its key, parent, operations, and actions in one table before the first path, then compile the table and check that every path matches a row.
Extract a semantic model from a spec 2 guides
Turning endpoints into entities, attributes and operations: classification heuristics (which path is a list, load, create, update or remove), handling endpoints that map to no entity (direct and prepare escape hatches), flows, inconsistent specs, diffing two models from successive spec versions, publishing the model as JSON beside OpenAPI, and verifying that SDK, CLI and MCP server were generated from the same model version.
Diff two semantic models from successive spec versions
Extract a model from each spec version, diff the two model files, and read the result beside what oasdiff and openapi-diff report about the same release.
Reconcile an extracted entity model with a domain model
Put the entity model extracted from the spec beside the one your team drew, give each disagreement a row and a decision, and fail the build when one has neither.
Describe an API without OpenAPI 1 guide
When OpenAPI is the wrong tool: TypeSpec, Smithy, AsyncAPI, GraphQL SDL, protobuf, Arazzo workflows, JSON Schema alone, and converting legacy RAML and API Blueprint.
Describe payloads in JSON Schema alone and generate types
Publish standalone JSON Schema 2020-12 files, bundle them offline, generate TypeScript and Python types, and wrap them in an OpenAPI 3.1 shell when a tool insists.
Version and retire APIs 2 guides
Versioning strategies (path, header, date-based as Stripe does), additive change rules, breaking-change detection in CI (oasdiff, openapi-diff, Optic, and aontu breaking and subsume as one option for model files), Sunset and Deprecation headers, deprecation calendars, compatibility tests, and tying SDK versions to API versions (the sdkgen api-versioning design note as one approach beside Stainless and Speakeasy).
Detect breaking changes between two OpenAPI versions in CI
Fail a pull request whose OpenAPI change would break existing clients: bundle both sides with one tool, run oasdiff, and post its verdict as a comment.
Pin an API version from a client
Send the API version you were built against on every request, and refuse a response that came back under a different one.
Section 6
Ship an SDK
23 guides in 6 topics
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 5
- Design SDK ergonomics per language 5
- Compose runtime features in an SDK 4
- Customize a generator without forking 5
- Target another language 3
- Regenerate without losing edits 1
Choose a generator and generate an SDK 5 guides
Deciding and doing: a repeatable rubric for hand-written versus generated versus AI-written versus SaaS-generated SDKs (total cost of ownership, per-seat pricing, determinism measured across two runs, entity-shaped versus endpoint-shaped output measured rather than asserted), then running OpenAPI Generator, Swagger Codegen, Kiota, Speakeasy, Stainless, Fern, liblab, oapi-codegen, openapi-typescript with openapi-fetch, orval, Hey API, openapi-python-client, NSwag, AutoRest, Smithy, and sdkgen (npm create @voxgig/sdkgen, target add, --only, --dryrun), judging the output (the voxgig-solardemo-sdk Go reference and the elementdemo repo as things to read before choosing), and migrating from one generator to another while keeping package names and semver continuity.
Decide between generating and hand-writing a client
Count the operations, schemas and parameters you would maintain, then decide between a generated client and one you write on the numbers rather than on taste.
Generate an SDK with Fern from generators.yml
Set up a Fern project from an OpenAPI document, read the generators.yml it writes, validate it offline, and know which generator group runs before anything runs.
Generate one SDK from several OpenAPI documents
Join one document per service under a prefix rule fixed before the first merge, generate one package from the result, and test that no name moves.
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.
Tell an entity-shaped SDK from an endpoint-shaped one
Count the nouns, the operations per noun, and how many names start with a verb, so a claim about SDK shape is a measurement rather than a preference.
Design SDK ergonomics per language 5 guides
What makes an SDK feel native: entities versus endpoint wrappers, constructor and configuration, method naming, options objects versus builders, sync and async variants, cancellation (context.Context, AbortSignal), typed errors, nullable handling, response envelopes, ESM and CJS dual builds, and escape hatches for raw requests (sdkgen direct and prepare, Stainless raw responses, OpenAPI Generator withHttpInfo).
Build a PHP SDK that takes any PSR-18 HTTP client
Type a PHP SDK against the PSR-18 and PSR-17 interfaces, let callers pass the HTTP client they already run, and fail with an install command when none is present.
Expose typed SDK errors callers match without parsing text
Turn HTTP failures into a small error hierarchy carrying status, a stable code, the request id, and the raw body, and test that each status maps to one type.
Give a Ruby SDK keyword arguments and Faraday middleware
Give a Ruby client keyword-argument methods and Data response objects, let callers add Faraday middleware, and prove a wrong keyword raises before any request.
Offer sync and async clients from one Python SDK
Write the client once as coroutines over httpx, generate the sync twin with unasync at build time, and pin both to one method set with a test.
Shape an SDK around entities instead of endpoint wrappers
Decide the home entity of every operation before you pick a generator, test the three documented call chains, and see what two generators guess.
Compose runtime features in an SDK 4 guides
How cross-cutting behaviors fit together inside one client, and the smaller behaviors a client carries: permission hints, proxy routing, debug buffers, structured logs, request tracking, audit records and cost attribution.
Choose the pipeline stage where an SDK behavior should run
Place each cross-cutting behavior at the sdkgen stage that holds its input, and prove with forced failures which stages a call runs and which it skips.
Tag SDK calls with session and request ids
Send three identifiers with three lifetimes, so a support question about one call can be answered from the service's own logs.
Wrap an SDK transport in a middleware chain
Compose retry, caching, authentication and tracing as layers around one transport, so each concern is written once and the order is declared rather than implied.
Write an audit record for every SDK call
Write one record per logical SDK call, naming the caller, the operation, the entity, and the outcome, to an append-only sink, and never one record per HTTP attempt.
Customize a generator without forking 5 guides
Bending generated output without a fork: OpenAPI Generator custom templates and .openapi-generator-ignore, Speakeasy overlays and hooks, Fern custom code, Kiota, and the six sdkgen levers (model .aon files with project.aon never overwritten, templates in .sdk/tm, TypeScript components in .sdk/src/cmp, custom features with per-stage hooks, custom targets, and sdkgen packages with package add, check, list, update), plus docs add, the flags --only, --alias, --force, --dryrun and --debug, typed models, doctor in CI, installing a third-party sdkgen package such as @voxgig/sdkgen-haskell or sdkgen-station, propagating template changes, migrating a bundled target out of tree, driving generation from a script with the programmatic API, and debugging generation.
Fail a build when a generator customization becomes a fork
Record what the generator shipped, compare the project against it on every build, and separate a file you forked from a file you added.
Find which template produced a generated file
Read the FILES manifest for what OpenAPI Generator wrote, search its extracted template set for the file's text, and prove the match with a one-line marker.
Generate a code section with code instead of a template
Write a client's computed parts, a dispatch table and an overload matrix, as a function over the typed model, and hold its output to a formatted fixture.
Package a customization several SDK projects can install
Turn a feature you copy between sdkgen projects into a versioned package, install it into two projects, and roll both forward while each keeps its own settings.
Rename a generated SDK method without editing the output
Rename a generated method where its name is decided, in the OpenAPI document or in the generator, regenerate, and prove the rename reached every target.
Target another language 3 guides
Adding a language to an SDK programme: how to grade targets yourself when the generator does not (sdkgen publishes 22 bundled targets plus package-delivered ones such as Haskell, but grades none of them; OpenAPI Generator labels each generator's stability; Speakeasy publishes a supported-language list), what less polished should mean to you, packaging expectations per ecosystem, and authoring a new target (sdkgen author-a-new-language, OpenAPI Generator new-generator scaffolding, the Fern generator API).
Decide which SDK language to add next
Rank candidate SDK languages from tickets, signup answers, registry counts, and the User-Agents of raw API calls, the source that sees users you have not reached.
Evaluate a third-tier SDK target before you ship it
Run one fixed evaluation on a candidate language target, record what you measured beside the generator's claims, and decide who supports it before it ships.
Set support tiers for your SDK languages
Write each SDK language's tier as data, generate the CI matrix and the published support table from it, and fail any release that broke a tier's promise.
Regenerate without losing edits 1 guide
Regeneration as a routine operation: three-way merge against the last generation, preserve and protect markers, diff mode, overwrite policies, reviewing a regeneration diff, failing CI when a regenerated SDK differs from the committed one, vendoring and upgrade migration, keeping hand edits in separate files.
Preview a regeneration as a diff before writing files
See exactly what a generator would change before it changes anything, with a dry run that reports creates, replacements, and the files its mode protects.
Section 7
Ship a CLI or REPL
15 guides in 4 topics
Command-line and interactive surfaces over an API, for humans, scripts and agents: building, making usable, distributing, and exploring an API before writing code.
- Build a CLI over an API 3
- Make a CLI usable by people, scripts and agents 3
- Test, package and distribute a CLI 3
- Explore an API interactively 6
Build a CLI over an API 3 guides
Generating or hand-writing a CLI: restish over any OpenAPI document, the go-cli target generated from a semantic model, oclif and commander, cobra, click and typer, clap, Thor, Symfony Console, and a gh-style resource-shaped command tree; mapping operationIds to commands, flags and auth, and curl plus jq or HTTPie as the do-nothing baseline.
Derive a noun-verb command tree from an OpenAPI document
Turn operationIds, tags and paths into a committed map of noun, verb and operationId that any CLI framework can implement, with collisions resolved in the map.
Map API parameters to CLI arguments and flags
Extend the command map with a parameter map: path parameters as positional arguments, query and header parameters as flags, and one input style for request bodies.
Wire OpenAPI security schemes into CLI auth flags
Turn each OpenAPI security scheme into a CLI flag backed by an environment variable, place the value where the scheme says, and prove it with a 401 and a 200.
Make a CLI usable by people, scripts and agents 3 guides
Output formats (table, JSON, YAML, --jq), stable exit codes, TTY detection and color, paging, progress, shell completion, help text, config files and profiles, environment variable precedence, keychain token storage after a device-flow login, and designing a CLI that a coding agent can drive.
Add a --json flag and stable exit codes to a CLI
Print one JSON document on stdout, every message on stderr, and a four-line exit code table in the help, then prove a script can branch on it.
Design a CLI a coding agent can drive
Give a CLI machine-readable output, exit codes that mean one thing each, and a confirmation rule that never depends on a terminal being attached.
Write CLI help that people and agents can both use
Describe the command surface once, render it as text and as data, and lint the result so a command cannot ship with an example that does not run.
Test, package and distribute a CLI 3 guides
Golden-file and snapshot tests across operating systems, end-to-end tests against a mock API, then distribution with goreleaser, Homebrew taps, Scoop, npm, pipx, Docker images, code signing and notarization, and update checks.
Cross-compile CLI release archives with goreleaser
Turn one tag into per-OS archives and a checksums file with goreleaser, a build script you own, or dist for Rust, and stamp the version so no binary says `dev`.
Snapshot-test CLI output across operating systems
Run the built CLI as a child process, normalize line endings, paths, and color, and compare with committed golden files on Linux, macOS, and Windows in one matrix.
Test interactive prompts and terminal behavior in a CLI
Test a confirmation prompt without a real terminal, by passing the streams and the terminal flag in rather than reading them from the process.
Explore an API interactively 6 guides
Trying calls before writing code: language REPLs with an SDK loaded and tab completion from the model, generated REPL surfaces (the sdkgen REPL, seneca-repl), prompt_toolkit and IPython shells, Postman, Bruno, Insomnia and Hoppscotch collections generated from OpenAPI and kept in git, GraphiQL, Swagger UI try-it, HTTPie sessions, and a keyboard-first command bar over an API's operations (cmdk, kbar, voxgig-ui as options).
Add a keyboard command bar over your API operations
Build a command palette over every operation in an OpenAPI document, opening in the sandbox and refusing a delete until its operationId is typed back.
Build a REPL for your API in Node.js
Wrap an API client in its own Node REPL: environment in the prompt, dot commands for state, one-line API errors, and a session that survives a background failure.
Generate a REPL from an OpenAPI description
Generate a shell from an OpenAPI document with the sdkgen Go CLI target, read what the model gave it words for, and point it at a sandbox before the first call.
Generate an API client collection from an OpenAPI document
Turn an OpenAPI document into a Bruno or Postman collection with one command, commit the output beside the document, and fail the build when the two stop agreeing.
Preload a generated client into a Node REPL
Start a REPL with the client already built and its entities named, so exploring an API is one command rather than six lines of setup typed from memory.
Turn an exploratory REPL session into a script
Convert a REPL history into a script that runs, by dropping the lines that threw, the expressions typed to look at a value, and the REPL's own commands.
Section 8
Expose your API to agents
26 guides in 6 topics
MCP servers, tool schemas, hosting and server-side policy, agent skills and instruction files, and making a site and its docs usable by autonomous callers.
- Build an MCP server 7
- Design tool schemas agents can use 4
- Host, transport and secure an MCP server 5
- Write agent skills and instruction files 4
- Make a docs site agent-ready 5
- Audit your API's agent experience 1
Build an MCP server 7 guides
Building an MCP server for an API, generated or by hand: openapi-mcp and openapi-mcp-generator, Speakeasy Gram, Stainless MCP, Mintlify, Zapier MCP, Composio, Cloudflare MCP, the go-mcp target generated from a semantic model (SDK Catalog servers, aontu-mcp and the tabnas mcp server as worked examples), and the official MCP SDKs (TypeScript, Python, Go, Java, C#, Rust, Kotlin, Swift) plus FastMCP; tools, resources, prompts, elicitation, wrapping an existing SDK as tools, pruning a generated server to a small tool set, regenerating when the spec changes without losing custom tools.
Generate an MCP server from an OpenAPI document
Run openapi-mcp-generator over an OpenAPI 3 document, build the stdio server it writes, and list its tools from a scripted client before any agent connects to it.
Keep an agent informed while an MCP tool runs for minutes
Send progress against the client's token, stop when the client cancels, and choose between one long call, a job id with a poll hint, and the tasks extension.
Prune a generated MCP server to ten tools an agent can use
Cut a generated MCP server from forty-one tools to ten, merging near duplicates behind an enum, and prove the same agent tasks still complete.
Run an MCP server against a mock API while you build tools
Point your MCP tools at a mock you can script, so a rate limit or a 500 is one line of fixture rather than a bad afternoon on the real service.
Serve reference data as MCP resources instead of tools
Serve plan limits, region codes, and a changelog as MCP resources behind URI templates, and keep one lookup tool for the clients that never read a resource.
Unit test MCP tool handlers without starting a server
Test tool logic with direct calls, the contract through the SDK's in-memory client, and the command line with one spawned stdio process.
Upgrade an MCP server to a newer protocol revision
Move a server from a handshake-era revision to 2026-07-28 by upgrading the SDK, then prove every client you support still connects with one scripted matrix run.
Design tool schemas agents can use 4 guides
Tools an agent can reason about: naming, descriptions, argument schemas, enums over free text, result shapes, errors as data that tell the agent what to do next, pagination inside a tool result without overflowing context, tool granularity (one tool per entity operation versus one search tool), annotations (readOnlyHint, destructiveHint, idempotentHint), versioning a tool set, and MCP schemas versus OpenAI function schemas versus Claude tool definitions versus Gemini function declarations.
Design filter and sort arguments for a list tool
Named properties, a query mini-syntax, or a filter object with sort enums: three argument designs for one list tool, scored on ten prompts, then made to fail loudly.
Map one tool definition to MCP, OpenAI, Claude, and Gemini
Emit the MCP, Claude, OpenAI, and Gemini formats from one tool definition, and prove each with a test that validates one known-good call.
Name tools so an agent picks the right one from fifty
Give every tool a noun and a verb, a description long enough to choose on, and a warning on anything destructive, then measure how often two tools still look alike.
Shape a tool result so an agent can reason about it
Return the fields an agent decides on, in that order, with the ids its next call needs, and measure what Markdown, compact JSON, and structuredContent cost.
Host, transport and secure an MCP server 5 guides
The server side of running MCP in production: stdio versus Streamable HTTP versus legacy SSE, stateless design, OAuth 2.1 with protected resource metadata, per-agent keys and scopes per tool, rate limits shaped for bursty autonomous traffic, audit trails, deny lists, sanitizing tool results against injection, hosting on Cloudflare Workers, Vercel and containers, server cards at /.well-known/mcp/server-card.json, server.json registry entries, and testing with MCP Inspector and scripted clients.
Choose between stdio and Streamable HTTP for an MCP server
Ship stdio when the agent runs beside your binary and Streamable HTTP when it does not, keep the tools in one module, and keep stdout clean.
Issue and rotate per-agent API keys for an MCP server
Give every agent installation its own key carrying the tools it may call, so a revocation stops one agent rather than every agent.
List an MCP server in the official MCP registry
Publish a server.json to the official MCP registry, prove your namespace from CI with GitHub OIDC, and keep the listing level with each release.
Record an audit trail of every MCP tool call
Write one record per tool call with the caller's identity, a keyed digest of the arguments, and the outcome, then ask the store which agent deleted a record.
Stop a runaway agent loop from exhausting your MCP server
Put a call budget, a concurrency cap, and a kill switch inside the server, keyed by identity, and refuse with an error the looping agent stops on.
Write agent skills and instruction files 4 guides
Documents an agent reads before it writes code, at repo and package level: AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, SKILL.md against the Anthropic Agent Skills spec with progressive disclosure and bundled scripts, generated skills from a semantic model (the sdkgen Agent Skills surface and aontu agentsmd as options, the tabnas skills repo as an example), what to include and keep out, stopping an agent editing generated files, testing whether Claude Code or Cursor actually uses a skill, keeping several formats in sync from one source, versioning with the code.
Migrate CLAUDE.md and .cursor/rules to AGENTS.md
Move the rules every agent needs into one AGENTS.md, keep each tool's file for what it alone understands, and measure what each tool loads before and after.
Organize agent skills across many related repositories
Keep one shared set of skills for the ecosystem, let each repository override what it needs, and report every shadowed name rather than letting one win in silence.
Scope agent instructions to one package in a monorepo
Give each package its own AGENTS.md, Cursor rule, Copilot instructions file, or Claude Code rule, and check which files each tool loads from inside one package.
Write a skill description that triggers at the right time
Write the description around the words users type and the files they edit, then score it on ten fixed prompts beside a Cursor rule and a Copilot path glob.
Make a docs site agent-ready 5 guides
A documentation or product site that agents can use: llms.txt and llms-full.txt, markdown twins and Accept: text/markdown negotiation, AGENTS.md at the site root, a published OpenAPI document at a stable URL, /.well-known/api-catalog (RFC 9727), MCP server cards, an agent-skills index, robots.txt rules per AI crawler, JSON-LD types, RFC 9457 errors on every route, a health endpoint, a docs-search MCP server, and validation tooling (Google Rich Results, the MCP registry CLI, schema linters), with the setup for Astro, Docusaurus, Mintlify and Next.js.
Add a health endpoint agents can poll
Return a status, a release id, and one line per dependency, cache it for seconds, and prove the endpoint goes red when a dependency goes down.
Make a Docusaurus site agent-ready
Generate llms.txt in sidebar order, a markdown twin of every page, AGENTS.md, and the OpenAPI document from a Docusaurus plugin, and fail the build on any drift.
Publish an OpenAPI document at a stable URL for agents
Serve the OpenAPI document as JSON and YAML at URLs that do not move, with the headers a browser needs, and a check that fails when the copies drift.
Set robots.txt rules for each AI crawler
Separate the crawlers that train models from the fetchers acting for a person right now, and check each rule against the matching algorithm before you ship it.
Write an AGENTS.md for the root of a documentation site
Serve a short AGENTS.md at your site root that tells an agent how to call your product, then prove every URL in it resolves and every command in it runs.
Audit your API's agent experience 1 guide
Testing your API and docs against real agents: scripted runs with Claude, ChatGPT, Cursor, Cline and VS Code as MCP clients, scoring task completion from the docs alone, catching error semantics that mislead agents (vague 500s, missing Retry-After), finding pages an agent cannot read, measuring token cost per task, and turning findings into a scorecard and backlog.
Measure the token cost of an agent task against your API
Read the usage fields from a scripted run, split each task's tokens between tool definitions, tool results, and reasoning, and find the costliest result.
Section 9
Use AI to do the integration
32 guides in 6 topics
Coding agents, MCP clients, agent frameworks, structured output, evals, observability, cost and safety on the consuming side.
- Write an integration with a coding agent 8
- Connect MCP clients to servers 4
- Build an agent that calls APIs 5
- Constrain model output to a schema 3
- Evaluate and observe agents 7
- Guard agents and add approvals 5
Write an integration with a coding agent 8 guides
Getting Claude Code, Cursor, Copilot, Codex CLI, Gemini CLI, Aider or Cline to write an API integration: prompting with the spec, feeding an SDK, a catalog SDK, a skill or the API's MCP server, stopping the agent inventing endpoints, reviewing generated code for missing retry and error handling, test-first loops, running the agent in a sandbox with a mock API, keeping generated files out of agent edits, and the experiments: measuring drift between two AI-written clients from one spec, comparing an AI-written client with generator output, and the hybrid workflow where an agent customizes a generated SDK without breaking regeneration.
Bootstrap an integration from a catalog SDK with an agent
Install a generated SDK from the voxgig-sdk catalog, point the agent at its entity methods, and keep the glue off raw calls with a test, a gate, and one live check.
Install an API skill and check a coding agent uses it
Install a vendor's published SKILL.md with its digest verified, lint the description the agent matches tasks against, and confirm the agent loads it.
Let a coding agent customize a generated SDK safely
Point the agent at the levers under .sdk/, never at the generated tree, and prove with doctor and a regeneration diff that only the intended files move.
Let a coding agent probe a live API through an MCP server
Give a coding agent a read-only probe of the real API while it writes the client, and check what came back against the document before the agent hard-codes it.
Measure drift between two AI-written clients
Compare two clients written from the same description and separate what one of them missed from what neither was told.
Run a coding agent headless in CI to keep a client current
Hand an upstream spec change to an agent in a read-only CI job, guard its patch, and open the pull request from a job that never holds the model key.
Stop a coding agent inventing endpoints not in the spec
Make an invented path a compile error, refuse the rest at a validation proxy, and review casts as well as tests, because an instruction on its own leaks.
Write a task prompt that gets an API integration done
Name the spec, the auth scheme, the language, the test command, and the done criteria in one task prompt, then check the agent's result against them yourself.
Connect MCP clients to servers 4 guides
Wiring an MCP server into Claude Desktop, Claude Code, ChatGPT, Cursor, Cline, VS Code and custom clients: stdio versus remote configuration, OAuth in client config, restricting which tools an agent may call, running several servers at once, composing servers behind one gateway (mcp-proxy), running a stdio server as a subprocess from a Python agent, health checks, debugging with MCP Inspector, and using catalog MCP servers, aontu-mcp and the tabnas mcp server as ready-made examples.
Authorize a remote MCP server with OAuth from a client
Walk an MCP client through a protected server's OAuth flow, keep its registration and tokens where you can find them, and recover when the server forgets it.
Connect a remote MCP server to Claude Desktop
Get a remote MCP server answering tool calls in Claude Desktop, as a custom connector or through a stdio bridge, and probe its transport before blaming the config.
Health check your MCP server connections
Probe an MCP server three ways, see which probe notices an upstream credential that expired, and set one reconnect and backoff policy for stdio and remote servers.
Share one MCP server config across several editors
Keep Claude Code, Cursor, VS Code, and Cline on the same MCP servers by rendering four editor files from one source, and see why a copied file loads zero servers.
Build an agent that calls APIs 5 guides
Agent loops and frameworks: Claude Agent SDK, OpenAI Agents SDK, LangGraph, Vercel AI SDK, Mastra, CrewAI; wrapping a typed SDK as tools, converting OpenAPI operations into function schemas, auth passthrough, pagination in tool results, parallel tool calls, long-running operations, streaming tool output, multi-step workflows (Arazzo as a description format), and calling SDKs directly versus through MCP.
Build a stateful API agent with LangGraph
Read a record in one turn and write it back in the next, after a restart, carrying only its id and version in the state LangGraph saves at each step.
Build a tool-calling loop with the Claude Agent SDK
Call two REST operations from one agent three ways: the Claude Agent SDK query loop, the Anthropic SDK tool runner, and a loop you write over the Messages API.
Choose between calling an SDK directly and using MCP
Wire three API operations into one agent as in-process typed tools and as MCP tools, then measure startup, tokens per request, and what a rename breaks under each.
Stream partial tool output back to a user
Show a user the chunks a tool is receiving while the model waits, through AI SDK data parts, your own server-sent events, or Anthropic's input streaming.
Wire an API client into the OpenAI Agents SDK
Register a typed client's operations as function tools, run the loop, hand off between two agents on one client, and keep a failed call from ending the run.
Constrain model output to a schema 3 guides
Making a model emit valid data: JSON Schema structured outputs, tool-call schemas used as output, GBNF and Lark grammars for constrained decoding (llama.cpp, vLLM, Outlines, guidance), repairing malformed or truncated JSON, validating with Zod, Pydantic or gubu and retrying, and generating grammars from a spec (the aontu GBNF and Lark output and the tabnas GBNF grammar as options).
Generate a GBNF grammar from an aontu schema
Generate a GBNF grammar from an aontu model through its JSON Schema export, and find with a corpus which constraints only vet still enforces.
Serve schema-constrained output with vLLM
Pin a decoding backend, send the schema in the field this vLLM release reads, and run a harness that validates every reply and refuses a silent fallback.
Validate JSON model output before you use it
Get a typed value out of a model response that is only mostly JSON, and refuse the responses that are the wrong shape instead of letting them into your code.
Evaluate and observe agents 7 guides
Evals (promptfoo, Braintrust, Inspect, LangSmith, custom harnesses), golden traces, task success rates across model providers, regression suites for tool use recorded from real traffic, tracing with OpenTelemetry GenAI semantic conventions (Langfuse, Phoenix, Helicone, OpenLLMetry), token and cost accounting, per-task budgets as cutoffs versus hard caps (the sdkgen cost feature as one example), caching tool results across steps, prompt caching, model routing.
Account for tokens and cost per agent task
Read each provider's usage fields into exclusive token buckets, price them from a table you keep, and roll the money up per task and per tenant.
Cache tool results across the steps of one agent run
Cache an agent's read tools by tenant, tool and arguments, clear the cache on every write, and record requests saved beside whether the answer stayed right.
Compare agent task success rates across model providers
Run one tool-using suite against several providers with only the model varied, and report success with an interval by case, tokens, and wall time per model.
Cut agent cost with provider prompt caching
Order the request so the stable prefix comes first and the growing conversation last, place the breakpoints, and measure cache reads against a baseline run.
Redact prompts and tool results in traces before export
Hash or drop prompts, tool results, and exception messages in one OpenTelemetry span processor, so a hosted backend gets the span tree and timings without the data.
Replay recorded API traffic in an agent regression suite
Record an agent's tool calls once, commit the cassette without the key, and replay it in CI so an uncovered request fails instead of reaching the network.
Run agent evals in CI without flaky failures
Rerun each eval case, gate the pull request on the aggregate against a band from nightly history, and keep outages and ordinary variance from reading as regressions.
Guard agents and add approvals 5 guides
The agent side of safety: prompt injection defence for tool results, web pages and documents, isolating untrusted content, output filtering, allow lists, human-in-the-loop approval before destructive calls, MCP elicitation, dry-run modes, sandboxing, least privilege per tool, spend and blast-radius limits, guardrail libraries (OpenAI Agents SDK guardrails, Guardrails AI, NeMo Guardrails, Llama Guard), and testing against an injection corpus.
Add a dry-run mode to an agent's write tools
Give every write tool a dry-run flag the runner owns, answer the dry run from the server, a fake transport or a recorded plan, and diff it against the audit log.
Handle MCP elicitation requests in your agent client
Let an MCP server ask the person before a destructive tool runs: declare the capability, render the schema as a form, and answer accept, decline, or cancel.
Require human approval before an agent calls a delete tool
Pause the run when the model calls a delete tool, show a person the exact arguments, resume with their decision, and test that a rejection deletes nothing.
Sandbox an agent's shell and code execution
Run what an agent executes inside a boundary with no credentials, a scratch filesystem and a closed network, in Docker, a sandbox service or an OS-level sandbox.
Sanitize tool results before they re-enter the prompt
Extract readable text, strip zero-width characters, normalize to NFKC, cut to a byte budget, and wrap the result in a delimiter the system prompt names as data.
Section 10
Test and mock integrations
16 guides in 3 topics
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 7 guides
Standing in for the real API: Prism from an OpenAPI document, WireMock, MSW, nock, Mockoon, vendor sandboxes, record-and-replay (vcrpy, VCR, Polly.JS, go-vcr, responses, httptest), fault injection (Toxiproxy, chaos flags), and in-SDK mocks (the sdkgen test feature for an in-memory API and netsim for injected latency, 429s and outages as options).
Control which stub wins when mock rules overlap
Make stub precedence explicit in WireMock, MSW and nock, and fail a test when a stub never answers, so a catch-all cannot hide the specific case you just added.
Mock a generated SDK in your application tests
Run one set of assertions about your code against a vendor SDK four ways, then bump the SDK a minor version and see which strategy noticed the change.
Run a local mock API for frontend development with Mockoon
Describe routes, status codes, and delays in one Mockoon environment file, run it headless with the CLI, and point the screen you are building at it.
Run an in-memory mock of your API inside SDK tests
Build the client in test mode, seed it with records, and let the generated SDK answer its own calls from memory instead of reaching the network.
Serve your OpenAPI examples as mock responses
Wire the examples in your OpenAPI description to what the mock server returns, so the docs, the tests and the mock all show one payload.
Simulate slow and broken networks with Toxiproxy
Put Toxiproxy between a client and its dependency, slow, stall and cut the connection from the test, and prove each call fails at its time budget.
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 7 guides
Proving the implementation matches the description: Pact consumer-driven contracts (for an SDK consumer and for a vendor API you call), Schemathesis and Dredd property tests against a spec, Specmatic and Microcks, response validation middleware at runtime, and message contracts for service messages (seneca-msg-test as one option next to Pact message contracts).
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.
Contract test messages between services
Pin the body and the routing key of an event in a consumer contract, verify the publisher in CI, and see the three tools catch, or miss, a renamed topic.
Publish and tag pacts in a Pact Broker
Run the broker on Docker and Postgres, publish each pact under its commit and branch, and record deployments so the broker knows what runs where.
Run an OpenAPI document as a contract test with Specmatic
Keep one JSON example per documented response beside the document, run Specmatic in strict mode against the service, and fail the build when one is missing.
Test stateful endpoints with Dredd hooks
Make Dredd pass for reads and deletes that need a record first, without loosening an assertion, and fail loudly when a hook names a transaction that has gone.
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.
Run SDK test suites 2 guides
Layered SDK testing: unit tests per language, integration tests in a sandbox account, live suites with real credentials under rate limits, CI matrices across language versions, doc examples executed as tests, flaky-test policy.
Layer unit, integration, and live tests for an SDK
Split an SDK suite into unit tests on an injected transport, integration tests against a sandbox, and a guarded live suite. Each layer gets a command and a trigger.
Seed a sandbox account for SDK integration tests
Create every record an integration suite needs under a run id, delete them newest first in a hook that runs on failure too, and sweep what earlier runs left.
Section 11
Document and support developers
23 guides in 6 topics
Reference docs, guides, docs that ship inside packages, question answering over docs, developer relations, and measuring your own developer experience.
- Publish reference docs 5
- Write guides and quickstarts 2
- Ship docs with the code 4
- Answer questions over your docs 3
- Run developer relations 5
- Measure and audit developer experience 4
Publish reference docs 5 guides
Reference from the spec and the code: Redoc, Scalar, Swagger UI, Mintlify, ReadMe, Stoplight Elements, mkdocs-material (the docgen apidocs target as one generator option), per-language API references (typedoc, pkg.go.dev, Sphinx, phpDocumentor, YARD), try-it consoles, versioned docs, diagrams (Mermaid, the Voxgig diagram utility), and hosting where each language looks.
Add sequence diagrams to reference docs with Mermaid
Write an OAuth exchange or a webhook round trip as a Mermaid sequence diagram beside the reference page, check it against the spec in CI, and render it in dark mode.
Choose a renderer for your OpenAPI reference site
Rank your own schemas by what a renderer can get wrong, build the worst with every renderer you can run, score the rest by hand, and publish the table first.
Detect a reference site drifting from its OpenAPI spec
Fail CI when the built reference carries an operation the spec removed, lacks one it added, or shows a deprecated operation as current, and lint the spec first.
Make a Go client reference render correctly on pkg.go.dev
Doc comments in the syntax the Go formatter keeps, examples that run under the right symbol, and a local render check before a tag the module proxy keeps forever.
Organize a large OpenAPI reference by tags and tag groups
Group a 200-operation reference into tags and tag groups that every renderer shows, check each operation is two clicks away, and keep old deep links working.
Write guides and quickstarts 2 guides
Diátaxis structure for APIs, quickstarts that reach a first call in five minutes, task docs, code samples in six languages that do not go stale (tested in CI), changelog-driven migration guides, versioned guides.
Move guides to a new docs toolchain without breaking URLs
Build the redirect map from your sitemap and your logs, crawl every old URL against the new build before the switch, and audit the anchors a redirect cannot carry.
Turn a breaking release changelog into a migration guide
Diff the old and new API descriptions with oasdiff, group the breaks by the work they cause, add before and after code, and ship it with the release candidate.
Ship docs with the code 4 guides
README conventions per registry (npm, pkg.go.dev doc comments, PyPI long description, Packagist, RubyGems, LuaRocks), docstrings and typed signatures generated from the spec, a CHANGELOG inside the package, examples directories that run in CI, and generated READMEs (the sdkgen docs add target and seneca-doc as options against hand-written templates).
Document Seneca plugin message patterns inside the repo
Generate the pattern reference from the running plugin with seneca-doc, ship it in the README, and diff it against seneca.list() to catch messages an option adds.
Generate Go doc comments from OpenAPI descriptions
Generate a Go client with oapi-codegen, OpenAPI Generator, and sdkgen from one document, and count which summaries, descriptions, and examples reached the comments.
Generate Python docstrings and type hints from an API spec
Generate a Python client whose help() text and type hints come from the OpenAPI document, then measure which descriptions survived, are empty, or repeat the name.
Ship a changelog inside your published package
Put the changelog in the published artifact, and check in CI that it ships and that its newest entry matches the version being released.
Answer questions over your docs 3 guides
RAG and search over docs, specs and transcripts: chunking an OpenAPI document so retrieval returns whole operations, embeddings, hybrid search, citations, evaluation against real support tickets, and hosting (podmind as one production example beside LlamaIndex, LangChain, Cloudflare Vectorize, pgvector, Algolia DocSearch, Inkeep, Kapa).
Chunk an OpenAPI document for retrieval
Cut an OpenAPI description into retrieval chunks that are each one complete operation, so a top hit carries the whole parameter table rather than half a schema.
Host docs question answering on Cloudflare Workers
Embed the question with Workers AI, query a Vectorize index filtered to one docs version, and stream the answer with its sources over Server-Sent Events.
Re-index docs on release without serving stale answers
Build a new documentation index per release, promote it in one write, and fail a check whenever the live index was built from an older version than the docs.
Run developer relations 5 guides
Practitioner DevRel: community forums and office hours, changelog communication, sample apps, content calendars with non-vanity metrics, conference talks and speaker coaching (agenda tooling such as conf-agenda as one option), a technical podcast with editorial independence (Fireside as one example beside Software Engineering Daily and The Changelog), DevRel programme set-up and audit, and fractional CTO and developer management routines.
Audit a DevRel program in one week
List every DevRel activity on Monday, replace each count with an outcome from evidence by Thursday, and present a scored report with three changes on Friday.
Build a sample app that developers fork instead of ignore
Build one sample app with a key, a list, a form, and real errors, name its owner and omissions in the README, and link it only to hosts that can run it.
Choose a developer community platform for year one
Score Discord, Discourse, GitHub Discussions, Slack, and Zulip on search, moderation, identity, cost, and export, then commit to one platform for a year.
Run a changelog channel developers read in time
Carry breaking changes to developers by feed, email, chat, and widget, then score the channels by the keys still calling the old shape on the sunset date.
Run developer management routines as a fractional CTO
Set up a weekly update, one-to-ones, an architecture review, a decision log, and an escalation rule that run without you, then check them after a week away.
Measure and audit developer experience 4 guides
DX as a measured thing: time to first successful call, install friction, SDK adoption per language, error rates by endpoint, support ticket taxonomy, scoring error messages with a rubric, running a DX audit of your own SDK (the checklist a Developer Experience consultancy would use, written for you to run), and production-readiness reviews before a launch.
Choose developer experience metrics for your API
Pick a handful of numbers that move when you change something, and leave out the ones that move when marketing runs a campaign.
Run a developer satisfaction survey for your API
Draw the sample from keys that made calls, ask eight questions, and report every segment with the baseline metric behind each low score.
Score your API's error messages with a rubric
Sample fifty real error responses from the log, score each body 0 to 2 on six criteria, and publish the score per endpoint before anyone redesigns the errors.
Write a production-readiness checklist for a new SDK
Write the checklist your team signs before a first public SDK release: an owner and an exit criterion on every item, and a script that fails the items it can read.
Section 12
Release and secure packages
16 guides in 4 topics
Publishing to registries, versioning and release automation, supply-chain integrity, and hardening clients and servers.
- Publish to package registries 3
- Version, changelog and automate releases 3
- Secure the supply chain 3
- Harden clients and servers 7
Publish to package registries 3 guides
The mechanics of each registry: npm (provenance, scoped packages), PyPI (trusted publishing), Go modules (tags, major version paths, proxies), Packagist, RubyGems, LuaRocks, crates.io, Maven Central, NuGet, pub.dev, Swift Package Index, Hex; yanking; and releasing many SDKs from one commit or monorepo (changesets, release-please, goreleaser, repo-manager as one tool for many repos, the sdkgen release-and-tag flow).
Publish a Ruby gem to RubyGems.org with trusted publishing
Register the release workflow as a trusted publisher on RubyGems.org, pending or not, and let the job trade its OIDC token for a short-lived push key.
Recover when one registry upload fails mid release
Make each publish step ask the registry and skip what it holds, give each registry its own job, push the tag last, and know when to burn a half-published version.
Set up PyPI trusted publishing from GitHub Actions
Register the workflow on PyPI and TestPyPI, publish through pypa/gh-action-pypi-publish with id-token write, and check the record still matches the file.
Version, changelog and automate releases 3 guides
Semver for SDKs, deciding whether a regenerated SDK is a minor or major release, conventional commits, CHANGELOG generation, release candidates, human-gated production releases, deprecation policy and long-term support, scheduled live suites, regenerating SDKs in CI (the Speakeasy action, Fern CI, sdkgen doctor and release-and-tag as options).
Adopt conventional commits in an SDK repository
Write commits as type(scope): subject with a scope per language, enforce it with commitlint and a title check, and keep draft footers out of squash merges.
Choose a release automation tool for an SDK repository
Dry-run changesets, git-cliff, release-please, and semantic-release against a throwaway copy of the repository, then pick by where a person decides the release.
Generate a changelog from conventional commits
Turn a commit range into CHANGELOG.md sections grouped by release, with dependency bumps and regeneration noise filtered out rather than published.
Secure the supply chain 3 guides
SLSA levels, Sigstore signing and cosign, SBOMs (CycloneDX, SPDX), provenance attestations, dependency pinning and lockfiles, Dependabot and Renovate, Socket, secret scanning, CVE runbooks, reproducible builds as a security property, and the trade-offs of a zero-dependency policy (the Voxgig multi-language libraries as one example of that policy).
Automate dependency updates with Dependabot or Renovate
Configure Dependabot and Renovate side by side for an SDK repository: a release-age delay on every update, and automerge only for the updates that earn it.
Choose a SLSA build level for a package release pipeline
Grade each release pipeline against the three SLSA Build levels from its workflow and runner, then write the level each artifact tier must reach into one policy.
Write a CVE response runbook for an SDK
Take a private vulnerability report to a fixed release in every language you ship, then check the advisory against the OSV schema and your SDK list.
Harden clients and servers 7 guides
Runtime security for integrations: the OWASP API Security Top 10, TLS pinning, SSRF defence for user-supplied URLs, input validation at the boundary, mass assignment, security.txt (RFC 9116), secret redaction in logs and debug output, least-privilege tokens, dependency isolation, server-side key rotation.
Audit the scopes of the tokens your integrations use
Inventory every long-lived token your services and CI jobs hold, map each to a week of calls, and re-issue it at the smallest scope behind a flag.
Defend a URL-fetching endpoint against SSRF
Allowlist the scheme and port, resolve the name yourself, refuse special-purpose addresses, connect to the address you checked, and check again on each redirect.
Keep internal detail out of API error responses
Map every unhandled exception to an RFC 9457 problem with a correlation id, run the mapper everywhere, and scan responses for your own host names and table names.
Publish security.txt for an API
Serve an RFC 9116 security.txt so a researcher who finds a bug in your API knows where to send it, and add the expiry check that stops the file going stale.
Review an API against the OWASP API Security Top 10
Review a running API against the ten risks of the 2023 edition, recording a replayable request and an owner for every risk, and rank the gaps you find.
Rotate API keys without breaking your clients
Run two keys at once, watch which one each caller uses, and retire the old one on evidence rather than on a date somebody picked.
Test an API for broken object level authorization
Try every identifier with every credential and assert that a caller who does not own a resource gets the same answer as one asking for something that does not exist.
Section 13
Operate integrations in production
22 guides in 5 topics
For the team with many third-party APIs in production: choosing and upgrading SDKs, credentials, telemetry and metering, one control surface for outbound calls, and debugging what went over the wire.
- Evaluate, adopt and upgrade SDKs 6
- Load credentials and secrets 3
- Instrument and meter API calls 4
- Control outbound integrations from one place 7
- Debug an integration 2
Evaluate, adopt and upgrade SDKs 6 guides
Assessing an official, community or generated SDK before you depend on it (license, retry behavior, release cadence, transport control), wrapping it behind your own interface, pinning and vendoring, upgrading across a major with jscodeshift and ts-morph codemods, responding to Sunset headers, and using SDK Catalog packages for public APIs (install per language, offline test mode, the paired Go CLI, MCP server and REPL, direct and prepare for unmodelled endpoints, what unofficial means, and when Octokit or plain fetch is the better call).
Audit SDK retry and timeout defaults before adoption
Point a candidate client at a local stub that fails and hangs, then read its real retry count and tail latency off the stub instead of trusting its README.
Check whether a vendor SDK lets you control the transport
Run each candidate client behind a local CONNECT proxy, then through its own transport option, and record which ones still reach the vendor.
Evaluate a third-party SDK before you depend on it
Score each candidate client on license, release cadence, unreleased fixes, open issues, and support, from a dated snapshot instead of its star count.
Judge whether an unofficial SDK is safe to depend on
Run six checks over a candidate package before you add it, and separate the facts that should stop adoption from the costs you are choosing to take on.
Respond to a Sunset header in your client
Read Sunset, Deprecation, and the Link relations off every response, then open one ticket per endpoint per day with the days remaining and the successor.
Write a jscodeshift codemod for an SDK upgrade
Rename methods and reshape argument objects at every SDK call site with a jscodeshift transform, dry-run it, review the diff, and audit the misses with ts-morph.
Load credentials and secrets 3 guides
Where the secret lives and how code reaches it: environment variables and dotenv, Vault (agent and API), AWS Secrets Manager and Parameter Store, GCP Secret Manager, Azure Key Vault, 1Password Connect and CLI, Doppler, Infisical, SOPS, the external-secrets operator; rotation without downtime, local development, CI, serverless, failing fast on a missing secret, keeping secrets out of CI logs.
Give a Cloud Run service a secret at deploy or at run time
Mount a Secret Manager secret with --set-secrets, read it at run time with the client library or through sekreto, and see which path picks up a new version and when.
Load AWS secrets without a vendor SDK in every service
Read one Secrets Manager secret from Node, Go, and Python services through a sekreto chain or the AWS SDKs, and see what each path reaches and what it hides.
Load secrets in Lambda without a fetch per invocation
Read an API key from Secrets Manager once per execution environment, not per invocation, through the extension, the SDK, or sekreto, and count the calls.
Instrument and meter API calls 4 guides
OpenTelemetry traces and metrics for API clients, trace context propagation from SDK through gateway to service, request ids and correlation, audit logs, cost attribution per call and per tenant, sampling, client identification headers, dashboards (Grafana, Honeycomb, Datadog), and SDK-level telemetry, metrics, audit, cost and clienttrack features (sdkgen) as one option against OpenTelemetry auto-instrumentation and gateway analytics.
Choose the layer that instruments outbound API calls
Capture one retried call at four layers, from OpenTelemetry to the gateway log, and give the span to the one that names the operation, tenant, and attempt.
Export outbound call spans from a serverless function
Get the span for the API call your function made to the collector before the environment freezes: flush it, hand it to a runtime task, or let a sidecar drain it.
Propagate a request id through an SDK into server logs
Mint one id per logical request, send it on every retry as a trace id, a custom header, or baggage, and find that exact id on every line of the server log.
Set an SLO for a third party API you depend on
Set an objective for a dependency you do not run, measured from your client, with burn-rate alerts that page when the provider degrades, not when you ship a bug.
Control outbound integrations from one place 7 guides
One place to see and police every outbound call: API gateways used for egress (Kong, Envoy, Tyk), egress proxies, service-mesh egress, unified-API vendors (Merge, Nango, Paragon), automation platforms (Zapier, Make, n8n), feature flags and kill switches, and station (each SDK registered as a plugin; config, credential routing via sekreto, observe, police with allow, deny and budget, debug; reading the station-errors reference when a policy denies a call; the sdkgen-station feature package, station-view, seneca-station).
Bring Zapier and n8n calls under your outbound policy
Put automation workflows under the egress policy your services follow: self-host n8n behind the proxy, scope hosted keys, or rewrite as a service.
Choose between an egress gateway and an in-process library
Put outbound policy at the network edge or inside the process, and decide with a bypass test: one deny rule, three callers, and a record of who got through.
Decide between a unified API and direct integrations
Score one real customer request against a unified common model and against direct vendor calls, then check the escape hatch and token custody before you sign.
Give a vendor a stable egress IP to allowlist
Pin calls to a vendor that allowlists source addresses behind one reserved address, and prove it from inside a worker with an address echo service.
Kill-switch one vendor integration without a deploy
Stop every call to one vendor within seconds, return a typed refusal instead of a slow failure, and decide whether a refused call queues, degrades, or errors.
Route outbound API calls through an egress proxy
Send every outbound call through one proxy that holds the credentials, enforces a per-vendor policy, and logs every decision it makes.
Tell a denied outbound call apart from a vendor outage
Work out in a minute whether your own egress policy, the network, or the vendor stopped a call, by making the denial an error code the caller can branch on.
Debug an integration 2 guides
Finding out what went over the wire: mitmproxy, Charles, Proxyman, request logging, HAR files, replaying with curl, diagnosing TLS and proxy problems, content-type and encoding mistakes, debugging generated code (sdkgen --debug, the debug-generation guide, station-view), and a debug mode that dumps requests without leaking secrets.
Debug a query string the API rejects
Capture the query string your client sent, decode it, and compare it with the OpenAPI style and explode rules, so a 400 points at the one encoding fix it needs.
Reduce a failing SDK call to a minimal reproduction
Record the request an SDK sent, replay and shrink it with a fresh token, place the fault with a second client, and hand over a script that checks it still fails.
Section 14
Run message-based services
15 guides in 5 topics
The services behind an API: choosing an architecture, message-based services and pattern routing, entity persistence, providers for external APIs, and HTTP or edge exposure. Seneca is one option beside NestJS, Moleculer, tRPC, NATS, Temporal and Hono.
- Build message-based services 6
- Route messages by pattern 2
- Persist entities in services 1
- Wrap external APIs as providers 4
- Expose services over HTTP and at the edge 2
Build message-based services 6 guides
Services where everything is a message: Seneca (actions by pattern, plugins and priors, transports and seneca-mesh, seneca-user, seneca-petition, structured message tracing, seneca-msg-test, seneca-doc, seneca-repl), @voxgig/system and create-system (services loaded by convention, model-driven CLI adding entity, srv, msg, field, env), and ordu for ordered task pipelines, against NestJS modules, Moleculer actions, tRPC routers, Fastify plus a message bus, NATS services and Temporal.
Add health and readiness checks to a worker service
Give a worker with no HTTP port a liveness check that flags a stuck loop, and a readiness check that holds work until its broker and store answer.
Add user accounts to a message-based service
Give a Seneca system register, login and session-check messages with argon2id hashes, and keep the password out of every log line debug logging writes.
Limit concurrency in a message worker
Stop a worker pulling more messages than it can process, so a burst waits at the broker where an operator can see it instead of inside your process.
Override a service action without forking its plugin
Add a second Seneca action on a vendor plugin's pattern, call the prior, keep every field it returns, and refuse to load out of order.
Run service startup steps in a fixed order
Turn an improvised startup function into an ordered list of named steps that can stop the boot and say why, and pin readiness to the store actually being open.
Split a monolith into message-based services with Seneca
Put each module of a Node monolith behind a Seneca message pattern, keep its exports as a facade so callers and tests stay put, and find shared tables first.
Route messages by pattern 2 guides
Dispatch by matching properties inside a service: patrun (most-specific match wins, trie keyed by sorted property names, gex globs, add, find, list, remove), bloomrun, router libraries, rules engines (json-rules-engine, Drools), decision tables (GoRules ZEN) and plain switch or if chains, with benchmarks for your message mix.
Dispatch messages to handlers with a Map keyed by type
Replace a switch on message.type with a Map of handlers, so that adding one is a registration call, unknown types reach a fallback, and prototype keys stay out.
Dispatch messages with pattern matching in Python
Route messages in a Python worker with the match statement, using mapping and class patterns, guards, and a fallback, tested over a table of messages.
Persist entities in services 1 guide
Entity data in services: seneca-entity and its store plugins (Postgres, Mongo, DynamoDB, seneca-d1-store on Cloudflare) against Prisma, Drizzle, TypeORM, Knex and raw drivers; the repository pattern, store-agnostic tests, migrations, multi-store setups.
Choose an id scheme for service entities
Decide who mints an entity id, the service or the database, then choose a sequence, UUIDv4, UUIDv7, ULID, or nanoid by measuring index locality and order.
Wrap external APIs as providers 4 guides
Bringing third-party APIs into a service system as providers: the seneca-provider pattern (seneca-dtone-provider, seneca-attachmentav-provider), generating a provider from a spec (the sdkgen seneca-provider target), credentials, retries and testing for providers against recorded fixtures, versus the adapter pattern, Nango and Merge unified APIs, and hand-written service clients.
Decide which layer retries a failed vendor call
Give network errors, 429 responses, 5xx, and handler crashes one retry owner each among stripe-node, p-retry, and JetStream, then count vendor calls to prove it.
Map vendor error responses onto message errors
Map every vendor status and error code onto five outcomes inside a Seneca provider, reply with a coded error, and log the vendor's own code beside it.
Migrate a hand-written vendor client to a provider plugin
Replace each service's copy of a vendor client with one Seneca provider, moving callers through shadow reads until the legacy path's vendor calls reach zero.
Switch vendors behind one provider interface
Put two vendors behind one Seneca message, route by tenant and country, normalize both replies into one shape that keeps every field, and diff the two replies.
Expose services over HTTP and at the edge 2 guides
HTTP and edge fronts for message services: seneca-gateway-* (including seneca-gateway-cloudflare) and seneca-web-adapter-express against Hono on Cloudflare Workers, Express and Fastify routers, API gateways (Kong, APISIX) and serverless adapters; auth at the gateway, running the same service locally and at the edge.
Add auth at the gateway for a service system
Verify tokens once at the gateway, strip the identity headers callers send, and sign what it forwards, so a hand-set x-user-id cannot promote anyone.
Run one service locally and at the edge without forking it
Write the HTTP front once in the fetch shape, give Node a twenty-line adapter, and run one request suite against both fronts and a stand-in that has no Node globals.
Section 15
Parse, validate and transform data
16 guides in 4 topics
Reading the formats integrations depend on, building parsers from grammars, validating shapes at boundaries, and transforming nested data.
- Parse config and data formats 6
- Write a grammar and parser 7
- Validate data shapes 1
- Transform nested data 2
Parse config and data formats 6 guides
Each format and when to choose it: JSON, JSONC, JSON5, jsonic (unquoted keys, comments, implicit top level, plugins, jsonic-cli), YAML, TOML, INI, CSV (RFC 4180, headers, custom separators, streaming, strict and lenient modes), XML, Markdown, CSS, JSON Lines, Atom and RSS feeds, protobuf IDL and Zon; error positions, streaming large files, when lenient input is the wrong choice.
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.
Decide when lenient parsing is the wrong choice
Give a lenient parser to files people edit and a strict one to bodies programs send, keep the loaders apart, and let a test refuse a lenient import at the boundary.
Include one config file from another
Pull a shared fragment into a config file with @tabnas/multisource, track where each value came from, and refuse cycles and paths that leave the config directory.
Load a CSV into a DataFrame with the column types you want
Declare each column's type in pandas, Polars, or DuckDB, so ZIP codes and ids keep their zeros and a renamed or dropped column stops the load.
Parse one config format identically in TypeScript and Go
Compile one ABNF grammar with tabnas into a TypeScript and a Go parser, and run one corpus of accept and reject fixtures in both CI jobs to prove they agree.
Read a protobuf IDL file without running protoc
List the services, methods, and field numbers in a tree of .proto files from a script, and refuse the misspelled custom option that a plain parser accepts.
Write a grammar and parser 7 guides
Building a parser for your own format: ABNF (RFC 5234) compiled to a rule table with @tabnas/abnf (a state machine as data, not generated parser code), attaching behavior by rule name, extending an existing grammar without forking, inspecting with @tabnas/debug, railroad diagrams, the support libraries (expr, path, directive, hoover, multisource), an LSP and playground for your format, benchmarking with measure, and emitting GBNF for constrained decoding; against peggy, ohm, chevrotain, nearley, ANTLR, tree-sitter, Lark and hand-written recursive descent.
Add a literal to a JSON grammar without forking the parser
Add a date literal to a JSON parser with a tabnas lexer plugin instead of a copied grammar, and compare it with a peggy fork and a chevrotain subclass.
Attach parse actions to grammar rules by name
Keep the grammar as plain ABNF, bind behavior to the rule names the compiler assigns, and test that every handler still names a rule and fires after a rename.
Generate a parser for a custom format in Go
Build a Go parser for a nested config format with pigeon, participle, and the ANTLR Go target, and catch a PEG rule that doubles its work per level of nesting.
Recover from syntax errors and report several in one parse
Turn on error recovery in chevrotain, ANTLR, tree-sitter or Lark, collect every error in one pass, and test that recovery keeps its place inside nested brackets.
Remove left recursion from a PEG grammar
Rewrite a left-recursive rule so peggy accepts it, fold the action from the left to keep subtraction left-associative, and compare with ohm-js and nearley.
Write a Pratt parser for operator precedence in filters
Parse and, or, not, comparisons, and arithmetic with a table of binding powers and one loop, then measure it against layered grammar rules in peggy and Lark.
Write a recursive descent parser by hand in TypeScript
Parse a filter language with a tokenizer, a method per grammar rule, and peek and expect helpers, then measure it against the same grammar in peggy and chevrotain.
Validate data shapes 1 guide
Runtime validation of inputs, config and SDK responses, and exporting JSON Schema from a validator (for tool definitions and OpenAPI alike): Zod, Joi, Yup, Valibot, ArkType, io-ts, AJV with JSON Schema, Pydantic, go-playground/validator, and gubu (a schema that looks like the data, Required, Optional, Default, Min, Max, One, Exact, Check, Coerce, Email, Url, Uuid, JSON Schema export, TypeScript and Go).
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 2 guides
Getting, setting, merging, walking, injecting and transforming nested structures, and flattening API responses for analysis: lodash, ramda, immer, jq, JSONPath, JSON Pointer, json-patch, deepmerge, pandas.json_normalize, and struct (getpath, setpath, merge, walk, inject, transform, validate, flatten, ported to 23 languages at parity).
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.
Section 16
Model, configure and generate
10 guides in 5 topics
Spec languages for configuration, environment overlays, application models that generate artifacts, project generators, and templates that produce deterministic code.
- Unify configuration with a spec language 3
- Layer configuration across environments 1
- Model an application and generate from it 1
- Generate code and projects 2
- Engineer templates and AST transforms 3
Unify configuration with a spec language 3 guides
Configuration as a lattice: aontu (unification, types, defaults such as *8080 | integer, references, conjunction and disjunction, reading a contradiction error, the verbs vet, get, why, set, subsume, breaking, trim, relations, hash, mod, reaches, jsonschema; the LSP and the stdio MCP server) against CUE, Jsonnet, Dhall, Pkl, KCL and Nickel.
Explain why a unified config has a given value
Trace one field of a config unified from base, team, and environment files back to the line that set it, and fail CI when a field still rests on a default.
Let a coding agent edit a config spec without breaking it
Run counterexamples the spec must refuse beside vet, after every agent edit and at commit, so an agent that deletes a constraint to clear an error is stopped there.
Reference one value from many places in a config spec
Name a service once and build its host name, log prefix, and queue name from it in CUE, Dhall, Jsonnet, and Nickel, then see which references survive a refactor.
Layer configuration across environments 1 guide
Configuration as data: Kustomize overlays, Helm values, YAML anchors, Jsonnet, Dhall, Pkl, KCL and CUE for environment layering; validating manifests in CI, removing duplication, migrating between languages, keeping secrets out of config, and when a unification language earns its keep.
Diff rendered manifests per environment before you merge
Render each overlay from a pull request and from its base, diff every environment with dyff, and post the result as one comment before anything merges.
Model an application and generate from it 1 guide
One model for entities, services, messages, fields and environments, then generating artifacts from it: @voxgig/model (unify .aon files into one model.json, actions that generate artifacts, --watch), model-react and model-vue bindings, and the early-stage apigen and udk projects.
Rebuild artifacts on model change with a watch loop
Regenerate TypeScript types and SQL within a second of a model edit, keep the last good output when a generator fails partway, and make the watch loop log why.
Generate code and projects 2 guides
Scaffolding and repeatable generation: jostraca (component tree of Project, Folder, File, Content, Fragment, Slot, Inject, Copy; define then build; in-memory generation for tests; byte-identical TypeScript and Go implementations; inks interpolation) against Yeoman, Plop, Hygen, Cookiecutter, Copier, Nx generators, Projen and Rails generators; plus pushing one template change to hundreds of repositories (repo-manager, the gh CLI, the Terraform GitHub provider, Renovate presets).
Push one CI template change to five hundred repositories
Fan one workflow change out over hundreds of repositories with a dry run, a checkpoint and three known end states, against four ways to stop copying the file.
Scaffold a Python API client project with Cookiecutter
Turn a Python client layout into a Cookiecutter template with derived names, a hook that survives a second run, and a test that bakes it into a temporary directory.
Engineer templates and AST transforms 3 guides
Deterministic generated code: EJS, Handlebars, Mustache, Jinja and Go templates; AST-based generation with ts-morph, jscodeshift and go/ast; codemods across generated files; formatting after generation; golden-file and snapshot tests of generated output; stable ordering and no timestamps.
Format generated code as the last step of generation
Format generated TypeScript, Go, and Python in memory with the consuming project's settings, before the generator writes, so no run needs a formatting commit.
Make a Handlebars template produce byte-identical output
Sort the model, keep helpers pure, normalise line endings and compile strict, so a Handlebars template renders the same bytes everywhere, checked with sha256sum.
Run a codemod across every generated file with jscodeshift
Rename a method across a directory of generated TypeScript with a jscodeshift transform, prove a second run changes nothing, then move the change into the template.
Section 17
Maintain libraries across languages
13 guides in 4 topics
For library maintainers: porting with parity, one test corpus for every port, plugin systems that work the same everywhere, and the small utilities that recur.
- Port a library across languages 3
- Test once, run in every language 2
- Design a plugin system 3
- Choose and build small utilities 5
Port a library across languages 3 guides
The canonical-plus-ports pattern (a TypeScript canonical, ports kept at parity: struct in 23 languages, plugin in 17, sekreto in 12, aontu, jostraca and apidef in Go), byte-identical output checks, idiom versus parity trade-offs, first-tier versus second-tier polish, release cadence across ports; compared with transpiling, sharing one implementation through WASM (wasm-bindgen, Extism) or FFI, and independent reimplementations (jq clones, lodash ports).
Choose between porting a library and reimplementing it
Decide how a library reaches a second language by running one shared case against every candidate, and record which reimplementations already disagree with it.
Release every port of a library on one version number
Link a canonical library and its npm, PyPI, Go, and Rust ports to one version, tag the Go module where Go looks, and check every artifact before anything publishes.
Share one implementation across languages with WebAssembly
Compile one Rust core to WebAssembly, call it from Node, Python, and Go through thin wrappers, and measure what the boundary costs before you retire a port.
Test once, run in every language 2 guides
One spec, many languages: JSON test corpora authored once and run by a per-language runner, omni (24 languages, zero runtime dependencies), the corpora behind struct, jostraca, aontu and the sdkgen .sdk/test/feature files, compared with Cucumber and Gherkin, JSON fixtures with hand-written runners, property-based testing (fast-check, Hypothesis, gopter) and Pact; corpus design, golden files, marking a case as expected to differ in one language, reporting parity gaps.
Choose between a shared test corpus and Pact contracts
Test each port's own logic with a shared corpus and its HTTP calls with Pact, and know which bug each one cannot see.
Design the case shape of a language-neutral test corpus
Fix the fields every case carries before you write a second runner: a stable id, a doc line, one input, one expectation, and sentinels for what JSON cannot say.
Design a plugin system 3 guides
Extending an application or library without forking it: @voxgig/plugin (definition, instance, declared, loaded and live lifecycle, reversible activation, 17 languages), the ESLint, Vite and Rollup plugin models, pluggy, the Go plugin package and hashicorp/go-plugin, OSGi, Ruby gem hooks, sandboxing third-party plugins, and sdkgen packages as an applied example.
Discover installed plugins without explicit registration
Find plugins because they are installed, with Python entry points, a gem file convention or a Node prefix scan, and refuse to start when two claim one name.
Run two instances of one plugin definition side by side
Declare one plugin definition under two refs, each with its own options, state, and connection, and reconfigure one without touching the other.
Test a plugin through every lifecycle stage
Drive one plugin from registration through activation to deactivation inside a test, and assert what it released, without touching a real network.
Choose and build small utilities 5 guides
The small libraries that recur in integration code, each against its mainstream peer: nid against uuid, nanoid and ulid (for idempotency keys and request ids); eraro against VError, Error.cause and Error subclasses; gex against minimatch and picomatch; inks against template literals and Mustache; ordu against p-series and a task queue; norma for argument normalization; and when to write your own versus depend.
Accept optional and reordered function arguments
Match a call's arguments against a pattern of names and types, so one function accepts several shapes without a chain of typeof checks.
Decide whether to depend on, copy, or write a utility
Check each small dependency for a built-in, a risky edge, a one-line rewrite, or code you can copy, and test the replacement before the package goes.
Measure what a small dependency costs before you add it
Take four numbers for a one-purpose package, install size, bundle bytes, parse cost, and maintenance, and set them beside a copy and a version of your own.
Package one utility for Node, Deno, Bun, and browsers
Publish one zero-dependency function so it imports cleanly in Node, Deno, Bun, and a bundler, and prove it against the packed tarball rather than the source tree.
Wrap errors with Error.cause and keep the original stack
Wrap a failed fetch or query in a domain error with the cause option, and keep the original error, its stack, and its code reachable.
No guides match that search. Try one word, or clear the box.
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.