What Is Contract-First Development?
The API spec becomes the agreed source of truth before code is written.
Read articleTopic
API Design
The Most Useful API Review Starts With a Diff, Not a Demo
A demo shows that the new path works. A contract diff shows what existing callers now have to survive. Here is a focused way to review an API change without turning it into a committee meeting.
Read articleYour cURL Command Works. That Doesn't Make It API Documentation.
A working request is a great starting point. Before handing it to another developer, answer the questions a cURL command cannot: what is required, what can vary, and what happens when it fails?
Read articleYour 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 articleYour 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 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 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 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 articleOpenAPI servers and server variables: local, staging, production, regions, and per-tenant hosts from one spec
Hardcoding 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 article