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.
136 guides in 17 sections, with code in JavaScript, PHP, Python, Ruby and TypeScript. Each section splits into topics, and each topic holds the guides.
Section 1
Authenticate and authorize calls
6 guides in 2 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 5 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.
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.
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 1 guide
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.
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.
Section 2
Make calls that survive failure
14 guides in 5 topics
Timeouts, retries, backoff, rate limits, idempotency, caching and error handling, on the client and server side of any API. These branches own the behavior; an SDK feature that implements it is one option here.
- Set retries and timeouts 4
- Set and respect rate limits 1
- Make writes safe to retry 1
- Cache API responses 2
- Handle and design API errors 6
Set retries and timeouts 4 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 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 1 guide
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.
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.
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 2 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.
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 6 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 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.
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
13 guides in 3 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 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 2 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.
Run bulk jobs and move files 2 guides
Bulk import and export, batch endpoints, async jobs with status polling, multipart and resumable uploads (tus, S3 multipart), presigned URLs, and large downloads.
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.
Section 4
Integrate beyond REST
5 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 1
- Consume and publish events 1
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 1 guide
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).
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 1 guide
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.
Section 5
Describe your API
7 guides in 6 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 2
- Author or repair a spec with a coding agent 1
- Lint and govern API specs 1
- Model resources, relations and actions 1
- Extract a semantic model from a spec 1
- Version and retire APIs 1
Write an OpenAPI description 2 guides
Writing OpenAPI 3.1 that tools can use: operationIds (snake_case, unique, verb plus noun, one page on ids that 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.
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.
Author or repair a spec with a coding agent 1 guide
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.
Lint and govern API specs 1 guide
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.
Model resources, relations and actions 1 guide
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.
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.
Extract a semantic model from a spec 1 guide
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.
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.
Version and retire APIs 1 guide
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).
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
10 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 3
- Design SDK ergonomics per language 1
- Compose runtime features in an SDK 2
- Customize a generator without forking 2
- Target another language 1
- Regenerate without losing edits 1
Choose a generator and generate an SDK 3 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 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 1 guide
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).
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.
Compose runtime features in an SDK 2 guides
How cross-cutting behaviors fit together inside one client, plus the behaviors that have no protocol branch of their own.
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.
Customize a generator without forking 2 guides
Bending generated output without a fork, with every page showing the same customization in at least one other generator: 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.
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.
Target another language 1 guide
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, and 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).
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.
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
7 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 2
- Make a CLI usable by people, scripts and agents 2
- Test, package and distribute a CLI 1
- Explore an API interactively 2
Build a CLI over an API 2 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.
Make a CLI usable by people, scripts and agents 2 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.
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 1 guide
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.
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 2 guides
Trying calls before writing code: language REPLs with an SDK loaded and tab completion from the model, generated REPL surfaces (the sdkgen REPL as in the existing blog post, 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).
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
11 guides in 5 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 3
- Design tool schemas agents can use 1
- Host, transport and secure an MCP server 3
- Write agent skills and instruction files 1
- Make a docs site agent-ready 3
Build an MCP server 3 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.
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.
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.
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 1 guide
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.
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.
Host, transport and secure an MCP server 3 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.
Write agent skills and instruction files 1 guide
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.
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.
Make a docs site agent-ready 3 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); per-framework implementation pages 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.
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.
Section 9
Use AI to do the integration
12 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 5
- Connect MCP clients to servers 2
- Build an agent that calls APIs 1
- Constrain model output to a schema 1
- Evaluate and observe agents 1
- Guard agents and add approvals 2
Write an integration with a coding agent 5 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.
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.
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 2 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.
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.
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 1 guide
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.
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 1 guide
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).
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 1 guide
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 with its limit stated), caching tool results across steps, prompt caching, model routing.
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.
Guard agents and add approvals 2 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 (this branch owns approval), 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.
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
7 guides in 2 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 4 guides
Standing in for the real thing: 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).
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 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.
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 3 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.
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.
Section 11
Document and support developers
11 guides in 5 topics
Reference docs, guides, docs that ship inside packages, question answering over docs, developer relations, and measuring your own developer experience.
- Publish reference docs 2
- Ship docs with the code 3
- Answer questions over your docs 3
- Run developer relations 2
- Measure and audit developer experience 1
Publish reference docs 2 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.
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.
Ship docs with the code 3 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 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 2 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.
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.
Measure and audit developer experience 1 guide
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.
Section 12
Release and secure packages
7 guides in 3 topics
Publishing to registries, versioning and release automation, supply-chain integrity, and hardening clients and servers.
Version, changelog and automate releases 1 guide
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).
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 1 guide
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.
Harden clients and servers 5 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, this branch owns it), 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.
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
7 guides in 4 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 2
- Load credentials and secrets 1
- Instrument and meter API calls 2
- Control outbound integrations from one place 2
Evaluate, adopt and upgrade SDKs 2 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, REPL and MCP server, 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.
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.
Load credentials and secrets 1 guide
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.
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 2 guides
OpenTelemetry traces and metrics for API clients (this branch owns the plumbing), 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.
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.
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 2 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).
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.
Section 14
Run message-based services
6 guides in 4 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, with Seneca as one option beside NestJS, Moleculer, tRPC, NATS, Temporal and Hono.
- Build message-based services 2
- Route messages by pattern 2
- Persist entities in services 1
- Expose services over HTTP and at the edge 1
Build message-based services 2 guides
Services where everything is a message: Seneca (actions by pattern, plugins and priors, transports and seneca-mesh, this branch owns transports, 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.
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.
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.
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 (the decide utility) 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.
Expose services over HTTP and at the edge 1 guide
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.
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
7 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 2
- Write a grammar and parser 2
- Validate data shapes 1
- Transform nested data 2
Parse config and data formats 2 guides
One page per format decision: 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.
Write a grammar and parser 2 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.
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.
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.
Validate data shapes 1 guide
Runtime validation of inputs, config and SDK responses, and exporting JSON Schema from a validator (this branch owns export, 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
3 guides in 2 topics
Spec languages for configuration, environment overlays, application models that generate artifacts, project generators, and templates that produce deterministic code.
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 1 guide
Deterministic generated code without a Voxgig tool: 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.
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.
Section 17
Maintain libraries across languages
3 guides in 3 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.
Test once, run in every language 1 guide
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.
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 1 guide
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.
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 1 guide
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.
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.