Guides

What the resource surface looks like before anything is sent over it.

• Choosing an API Style: REST, GraphQL, gRPC, Events, JSON-RPCWhen resource-oriented HTTP, GraphQL, gRPC, event-driven delivery or JSON-RPC is the right call, what each one costs you, and why most real systems use more than one.
• Filtering, Sorting & SearchingQuery parameter conventions for filtering, sorting, and full-text search, including operators, pagination interplay, and when to move complex queries to a request body.
• HATEOAS & Hypermedia APIsHow hypermedia controls make REST APIs self-describing through links in responses, the HAL and JSON:API formats, and an honest look at why adoption is limited.
• Multi-Tenancy PatternsDesign multi-tenant APIs with silo, pool, and bridge isolation, tenant routing, noisy-neighbor mitigation, and verified tenant claims.
• Pagination Patterns (Offset vs. Cursor)Detailed guide comparing offset and cursor pagination, detailing how to implement cursors and hypermedia headers.
• PATCH Strategies: JSON Patch vs Merge PatchComparing JSON Patch and JSON Merge Patch for partial resource updates, including null semantics and media types.
• Resource Naming & URI DesignConventions for naming resources and designing clean URIs: nouns over verbs, plural collections, sensible nesting, kebab-case, and path versus query parameters.
• Response Envelope DesignWeigh wrapping responses in data/meta/errors envelopes against bare bodies, and place pagination and error metadata consistently.
• REST API Design PrinciplesThe core constraints of REST: resources, statelessness, the uniform interface, correct verbs and status codes, and the Richardson Maturity Model.
• Sparse Fieldsets & Partial ResponsesLet clients request only the fields they need with sparse fieldsets, and expand related resources on demand to reduce payload size and round trips.
• Timestamps & Data FormatsConventions for representing time, money, enums, and nullability in JSON APIs: RFC 3339, always UTC, integer money, and consistent, unambiguous formats.

Which bytes come back, in which format, in which language.

• Content Negotiation & Media TypesLearn how content negotiation works in REST APIs, media types, and standard vendor extensions.
• File Uploads & DownloadsMultipart uploads, presigned and resumable uploads, Range requests, Content-Disposition, and streaming.
• Internationalization & LocalizationHow REST APIs negotiate language, separate message localization from data formatting, and standardize timestamps for a global audience.
• Media Types & Vendor Content TypesHow media types structure content, how the vendor tree and +json suffix work, and how to version APIs through the Accept header.
• Money, Decimals and Nulls in JSONRepresenting money as integer minor units or decimal strings, ISO 4217 currency codes and exponents, why floats and large JSON numbers lose data, and the difference between null, absent and empty, including under JSON Merge Patch.
• Resource Identifiers: Integers, UUIDs, ULIDs and Prefixed IDsChoosing public identifiers for an API: sequential integers versus UUIDv4, UUIDv7, ULID and prefixed opaque IDs, enumeration risk, why IDs are strings in JSON, case sensitivity, and why clients must never parse them.

Changing a published contract without breaking the clients on it.

• API Deprecation & SunsettingSignaling API retirement with the Deprecation (RFC 9745) and Sunset (RFC 8594) headers, Link relations, and migration timelines.
• API Versioning StrategiesCompare URI, Header, and Date-based versioning methods, and how to safely deprecate endpoints.
• Design-First Development and API GovernanceTreating the OpenAPI document as the source of truth: design-first against code-first, overlays instead of forks, a style guide enforced by a linter, breaking-change detection in CI, and a review process that looks at the contract rather than the code.
• Forward-Compatible EnumsHow to add enum values without breaking clients: open versus closed enums, the tolerant reader, documented unknown handling, OpenAPI and JSON Schema patterns, protobuf's UNSPECIFIED zero value and GraphQL's enum caveats.
• Generating SDKs from OpenAPIGenerated against handwritten client libraries, what an OpenAPI document needs before a generator can produce a good SDK, versioning the SDK separately from the API, and the retry, idempotency, pagination and User-Agent behavior an SDK should own.
• What Counts as a Breaking ChangeWhy the contract is what consumers observe rather than what you documented, which additive changes still break clients, and why fixing a bug can be a breaking change.

How the API behaves when the network, the caller or the server misbehaves.

• API Rate LimitingHow token bucket, sliding window, and fixed window algorithms work, and how to communicate limits with headers.
• Health Checks & Status EndpointsDesign liveness, readiness, and startup checks with the health+json format, dependency probes, and status pages.
• Idempotency & Request RetriesHow to implement idempotency keys, Redis-based locking, and safe client retry logic.
• Observability & Distributed TracingMake your API debuggable in production with structured logging, RED and USE metrics, W3C Trace Context, correlation IDs, and OpenTelemetry.
• Quotas & Usage MeteringHow a quota differs from a rate limit, how to meter usage without double-counting retries, how to tell clients where they stand, and what to return when the allowance runs out.
• Retries, Backoff & ResilienceIdempotent retries, exponential backoff with jitter, honoring Retry-After, circuit breakers, and timeouts.
• Standardized Error HandlingDesigning centralized error dictionaries, parsing field-level validation errors, and structure guidelines.
• Testing APIsWhere each kind of API test earns its place: consumer-driven and schema-based contract testing, generating inputs from OpenAPI, mocks that do not drift, and testing the error, retry and concurrency behavior that clients depend on.

Work that outlives a request, and the contracts for pushing it back.

• Asynchronous & Long-Running OperationsHandle long-running work in HTTP APIs with 202 Accepted, status polling endpoints, job resources, Retry-After, and the trade-off between polling and webhooks.
• Bulk & Batch OperationsHow to design batch endpoints, handle partial success, and process bulk writes idempotently and asynchronously.
• Streaming APIs: SSE, WebSocket & Long-PollingCompare Server-Sent Events, WebSocket, and long-polling, with guidance on reconnection, scaling, and when to use each.
• Webhook Delivery HistoryWhy recording the current state of a webhook delivery is not the same as recording its history, what each attempt should store, and how to make the record useful to the customer rather than only to you.
• Webhook Signature VerificationHow to verify incoming webhooks with HMAC-SHA256 signatures, signing secrets, timestamp-based replay protection, and constant-time comparison.
• Webhooks & Event-Driven API DesignBest practices for webhooks, covering secure payload signing, retry scheduling, receiver idempotency, and typed payloads whose changes are new event types rather than quiet mutations.

Not answering at all is faster than answering quickly.

• Cache Invalidation StrategiesA practical comparison of TTL, event-based, tag-based, and versioned invalidation, plus stale-while-revalidate and stale-if-error.
• CDN & Edge Caching for APIsHow to control shared caches with s-maxage, Vary, surrogate keys, and stale-while-revalidate to serve API responses from the edge.
• Conditional Requests & ValidationHow to use ETag, Last-Modified, and precondition headers to enable 304 responses and prevent lost updates in HTTP APIs.
• HTTP Caching & Conditional RequestsA developer guide on HTTP caching headers (Cache-Control, ETag) and conditional requests (If-Match, If-None-Match).
• HTTP CompressionHow APIs negotiate and apply gzip, Brotli, and Zstandard compression, and the caching and security considerations involved.

Proving who is calling, what they may do, and that nothing was tampered with.

• API Authentication SchemesA guide to HTTP-level authentication standards including Basic Auth, Bearer Tokens, and Message Signatures.
• API Security Best PracticesA practical checklist for securing HTTP APIs: TLS, authentication versus authorization, the OWASP API Security Top 10, input validation, rate limiting, and least privilege.
• Authorization Models: RBAC & ABACHow to choose and combine RBAC, ABAC, and ReBAC, apply least privilege, and prevent object-level authorization failures like BOLA.
• Cross-Origin Resource Sharing (CORS)Understand CORS, preflight OPTIONS requests, and access control headers in web APIs.
• Input Validation & Injection PreventionServer-side schema validation, allowlisting, and canonicalization, plus defenses against SQL/NoSQL/command injection and mass assignment.
• Logging Without Leaking: Secrets and Personal DataWhat an API must never write to its logs, why redaction belongs at the source, how to correlate requests without identifying people, and how retention and erasure apply to log data.
• mTLS & Client CertificatesHow mutual TLS authenticates both sides of an API connection, when to use it over bearer tokens, and how to manage certificate rotation and validation.
• OAuth 2.0 & API KeysHow API key authentication compares to OAuth 2.0, and when to use client credentials versus authorization code with PKCE.
• Outbound Request Safety and SSRFHow to fetch user-supplied URLs (webhooks, image imports, link previews, OAuth discovery) without letting a caller reach your internal network or cloud metadata service.
• Request SigningSigning outbound API requests with HMAC, AWS SigV4-style canonical requests, signed headers, body digests, and clock-skew handling.
• Token Lifecycle: Rotation, Refresh & RevocationManaging the full life of API tokens: short-lived access tokens, single-use refresh token rotation, revocation, introspection, and JWKS key rotation.

What survives when your API is read by a model rather than a person.

• Agent-Ready API ChecklistA review checklist for an existing API and its webhooks, covering the contract, errors, idempotency, deprecation, delivery and enforcement. Written for consumers that cannot ask you a question.
• Exposing an HTTP API as an MCP ServerBuilding a Model Context Protocol server in front of an existing API: curating tools rather than mirroring endpoints, choosing a transport, OAuth without token passthrough, returning errors the model can act on, paginating for a context window, and marking destructive operations.
• How an API Becomes Tool DefinitionsWhat an agent actually receives when your OpenAPI document is converted into tool definitions, which parts of the contract survive the conversion, and which are silently dropped.