Your Cancel Button Might Only Be Canceling the Spinner
Hiding a loading state does not stop work. Follow cancellation from the browser through queued requests and upstream services, then test the races users actually hit.
Read articleAuthor
Hiding a loading state does not stop work. Follow cancellation from the browser through queued requests and upstream services, then test the races users actually hit.
Read articleA green status code can hide a broken integration. Here are five checks that reveal what your happy-path request misses, with a small contract test you can run today.
Read articleA spec used only to render docs cannot stop a malformed request from reaching your handlers. Runtime validation middleware uses the same OpenAPI document to check incoming requests and outgoing responses, returning consistent 400s with field-level errors. Here is how request and response...
Read articleAgent work is long: research, multi-step tool calls, code generation. Blocking on one JSON response hides progress and hits timeouts. The Agent2Agent protocol models a task with explicit states, streams status and artifact updates over Server-Sent Events, and can deliver completion as a push...
Read articleThe security array means OR, any one listed scheme is enough; combining schemes inside one requirement object means AND, all are required. Get this backwards and an endpoint that needs both an API key and a bearer token accepts just one, or a public endpoint demands credentials. Here is how to...
Read articleLiveness and readiness are different questions: is the process running, and can it serve traffic right now including its dependencies? Collapse them into one /health endpoint and Kubernetes kills a pod briefly waiting on its database, or routes traffic to a half-warmed instance. Here is the...
Read articleOne OpenAPI document can render five very different doc experiences. We put a realistic OpenAPI 3.1 spec with webhooks, callbacks, polymorphic schemas, and security schemes through Swagger UI, Redoc, Scalar, Stoplight Elements, and RapiDoc, and compared try-it requests, code samples, advanced...
Read articleA written style guide that nobody reads drifts within a month; a Spectral ruleset that fails the build does not. Enforce operationId conventions, tag hygiene, error shapes, versioning, and security coverage with built-in and custom rules, then run them in CI and pre-commit. Here is a practical...
Read articleHardcoding https://api.example.com means the same spec cannot drive a local mock, a staging test, and a production call. Define multiple servers, use server variables for regions and per-tenant subdomains, and set a relative server for serverless and same-origin docs. Here is how codegen, mocks,...
Read articleoperationId becomes the method name in every generated SDK and tags become the namespace and the docs sidebar, yet most specs treat both as afterthoughts. Duplicate ids, verb-first names, and a unique tag per endpoint produce unusable clients and a wall of operations. Here is a naming system...
Read articleDeleting an endpoint is not a deprecation policy, and announcing it once in a changelog does not reach the integrations that actually call it. RFC 8594 gives you the Deprecation and Sunset response headers, Link rel=successor-version points at the replacement, and OpenAPI marks operations...
Read articleAPIs return more than JSON: CSV exports, PDF invoices, ZIP archives, resized images, and generated audio. Model them with the right media type and string/binary schema, document Content-Disposition and Range, and distinguish inline from attachment. Here is how to describe downloads, conditional...
Read article