Topic
Deleting 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 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 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 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 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 articleAn enum is a promise the server only accepts those values; a const is one fixed value; an open string accepts anything. Teams blur the three and ship a breaking change every time they add an option. Here is the decision table, extensible enums, and what codegen and AI callers do with each shape.
Read articleOptional, nullable, and omitted are three different facts most specs collapse into one. A field can be required yet nullable, optional but never null, or an array empty rather than absent. Here is the 3.1 decision table, and why one non-null sample never proves non-nullability.
Read articlePATCH is not PUT with fewer fields; the media type defines its semantics. JSON Merge Patch treats null as delete and replaces arrays; JSON Patch sends atomic operations and pairs with optimistic concurrency. Here is when to use each and the OpenAPI for all three.
Read articleA webhook is an inbound URL you register once; an OpenAPI callback is an outbound call whose URL arrives inside the request. Same shape, opposite direction. Here are the callbacks syntax, runtime expressions, a worked 202 example, and how to mock the round trip.
Read articleA payment can be a card, a bank transfer, or a wallet. Model that as a loose anyOf and generated clients fall back to any; model it as oneOf with a discriminator and you get a tagged union a compiler can narrow. Here is when each keyword applies and how to keep codegen, mocks, and AI callers honest.
Read articleA 429 with no Retry-After just makes clients guess, hammer harder, or give up. A usable rate-limit contract states the quota window, the remaining count, and exactly when to retry. Here is how to model 429, Retry-After, and the RateLimit headers in OpenAPI and verify the backoff with a mock.
Read articleTwo clients PUT the same resource and the last write silently wins. The HTTP fix is conditional requests with ETag, If-Match, and a 412 that tells the client to re-fetch and retry. Here is the exact state table and the OpenAPI that makes codegen and AI agents handle conflicts correctly.
Read article