Topic: api-design
-
Consistent API error responses with Problem Details
RFC 9457 defines a JSON shape for HTTP error responses (type, title, status, detail, instance) so that clients can handle errors uniformly; any consistent envelope with stable machine-readable codes achieves the same goal.
-
Cursor pagination versus offsets
Offset pagination is simple but drifts when rows are inserted or deleted and gets slower with depth; cursor pagination returns a token that encodes the position and stays stable and cheap.
-
Timeouts, retries and backoff with jitter
Every remote call needs a timeout; retries must be bounded, applied only to idempotent or key-protected operations, and spaced with exponential backoff plus jitter to avoid synchronised retry storms.
-
Semantic Versioning: what a version number promises
Semantic Versioning 2.0.0 encodes compatibility promises in MAJOR.MINOR.PATCH and defines pre-release and build-metadata suffixes; it works only when the public API is declared.
-
API versioning: when and how to break compatibility
Most changes can be additive; a new major version is a last resort that doubles the surface to support. Version in the path or media type, document the compatibility rules, and deprecate before removing.
-
Designing idempotent operations and safe retries
An operation is idempotent if repeating it has the same effect as doing it once; HTTP defines which methods are idempotent, and idempotency keys extend the property to POST so clients can retry without duplicates.
-
Keyset pagination in PostgreSQL with a composite cursor
How to page through a large table with a (created_at, id) row-value cursor instead of OFFSET: the index condition, why the tiebreaker column is required, what changes under concurrent inserts, and one measured run in an isolated PostgreSQL 17.11 database.
-
Input validation at trust boundaries
Validate every input where it enters the system: syntactic checks (type, length, format) first, then semantic checks against business rules; prefer allow-lists, reject rather than sanitise, and never trust client-side validation.
-
Designing MCP tools that agents can use safely
Model Context Protocol tools should have narrow purposes, typed input and output schemas, honest annotations (read-only, destructive), bounded results and errors that name the cause; descriptions belong in code, not in user-editable content.
-
HTTP caching with ETags and conditional requests
An ETag identifies a representation; If-None-Match lets clients revalidate cheaply with 304, If-Match protects writes against lost updates, and Cache-Control decides how long a response may be reused.
Machine-readable: JSON