Your API Returned 200. Your Integration Is Still Broken.
A 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 articleTopic
openapi
OpenAPI enums vs const: closed lists, open-ended strings, and how to add a value without breaking clients
An 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 articleRecursive and cyclic schemas in OpenAPI: self-referencing $ref for trees, nested comments, and graphs
Categories contain children, comments have replies, and org charts nest forever. Model these with a self-referencing $ref and generated clients produce recursive types that compile; inline the shape and codegen either loops or flattens it. Here is how to model trees, nullable children, oneOf...
Read articleOpenAPI additionalProperties: modeling maps, dictionaries, labels, and free-form objects without losing types
A JSON object is sometimes a fixed record, sometimes a Map<string, T> of arbitrary keys, and sometimes genuinely free-form. Use additionalProperties for dictionaries, properties plus additionalProperties:false for strict records, and an empty object for anything-goes payloads. Get it wrong and...
Read articlereadOnly and writeOnly in OpenAPI: one schema for create, response, and password fields
The server returns id, created_at, and version but must reject them on input; the client sends password and current_password that must never come back. One schema with readOnly and writeOnly properties models both directions and codegen splits it into request and response types automatically....
Read articleModeling money and big integers in OpenAPI: int64 precision, decimal amounts, and why number fails for currency
JSON numbers are parsed as doubles, so a 19-digit order id or an exact currency amount can lose digits the moment a client decodes them. Large ids often belong in strings, and money almost never belongs in type:number. Here is the precision table, the string-as-decimal pattern, and what codegen...
Read articleDates, times, and time zones in OpenAPI: date-time, date, duration, and the timezone mistakes that shift bookings
A timestamp with no offset is ambiguous, a calendar date is not a timestamp, and a duration is not a number of days. Teams conflate all three and silently shift reservations across time zones. Here is the RFC 3339 decision table, when to send an IANA zone versus an offset, and how to model...
Read articleIdempotency-Key in practice: retrying POSTs safely, deduping concurrent requests, and documenting it in OpenAPI
A network timeout never tells the client whether the charge happened. Retrying a plain POST double-creates; an Idempotency-Key header turns the retry into a replay. Here is the header contract, the in-flight 409 versus the stored response, key lifetime and scope, and the OpenAPI that makes SDKs...
Read articleBulk and batch API endpoints: modeling create-many, partial success, and 207 Multi-Status in OpenAPI
Looping 500 POSTs from the client is slow and fails halfway with no way to recover. A bulk endpoint accepts an ordered batch and reports each item independently, including partial success with 207 Multi-Status. Here is the request envelope, per-item status and error arrays, idempotency, and the...
Read articleLong-running REST APIs: 202 Accepted, Location, job status polling, and webhooks in OpenAPI
Holding an HTTP connection open for a three-minute export times out and ties up workers. Return 202 Accepted with a Location to a job resource, model the job state machine, and let clients poll or subscribe to a webhook. Here is the full lifecycle with progress and cancellation, and the OpenAPI...
Read articleDesigning a search endpoint in OpenAPI: q, filters, sorting, sparse fieldsets, and pagination codegen understands
A search endpoint decays into a pile of ad-hoc query params every client guesses at: filter[status], status_in, q, and a sort string nobody documents. Standardize full text with q, give filters explicit operators and types, use a sign convention for sort, and add sparse fieldsets for payload...
Read articleFile downloads in OpenAPI: CSV, PDF, ZIP, images, Content-Disposition, and non-JSON responses
APIs 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