API Contracts in Practice
Eight practical guides to OpenAPI, JSON Schema, consumer contracts, negative cases, API security, and AI-assisted drift analysis.
Series Chapters (8)
API Contract Testing with Playwright and JSON Schema
Playwright's request fixture gives you a browser-free API suite, but a schema check only catches a renamed or vanished field if it sets additionalProperties: false and keeps the name in required. This walks through the open-schema trap, the Ajv settings that decide whether failures are readable, generating schemas from an OpenAPI document, why allOf silently reopens a closed schema, and the honest boundary between schema validation and consumer-driven contract testing with Pact.
Turn a Postman Collection into Maintainable API Tests
A Postman collection is an exploration artefact: its run order is an undeclared dependency, its variables are five rungs of shared mutable state, and its assertions are usually copied from one captured response. This walks the Collection v2.1 JSON to inventory what you actually have, shows the Postman script beside the migrated Playwright test, and argues for keeping the collection for documentation and mock servers rather than deleting it.
Detect Breaking API Changes Before Consumers Do
A line diff cannot tell whether an OpenAPI edit invalidates an old request, widens a response beyond a client's decoder, or removes behaviour a consumer depends on. This guide builds a deterministic compatibility gate around a released baseline, a semantic report, consumer ownership, and two focused executable contracts, then shows what evidence an intentional break needs before approval.
Design Negative API Tests from the Contract
A negative test that asserts only a 4xx status is satisfied by a crashed pod, a rewritten gateway response, and a rejection that already decremented stock. This guide derives one invalid request per contract rule, places each mutation on the boundary the rule actually defines, and gives every case a three-part oracle: the exact status code, the machine-readable location of the violation, and a probe proving no forbidden side effect survived the rejection.
Test API Idempotency Under Retries and Timeouts
A sequential double-submit test passes on services that double-charge in production, because the dangerous retry follows an outcome the client never observed. This guide constructs that ambiguity deliberately with an aborted in-flight request, separates the four replays that must produce four different answers, and shows why the durable ledger count is the assertion that fails when a cached response body would have passed.
Test API Authorization Beyond Happy-Path Tokens
A valid token answers who is calling and nothing else. This guide separates the object, property and function questions the way OWASP's 2023 edition does, reads the security declarations most OpenAPI descriptions get wrong, and builds a deny-by-default grid whose denials are proved by comparison against a fabricated ID and whose rejected writes are read back by an identity that can actually see the field.
Verify Pagination, Filtering, and Sorting Contracts
Asserting page lengths and spot-checking page one is true of an endpoint that loses records. This guide builds a reference set whose total order you control, walks it by following the Link header instead of assembling URLs, and asserts membership, uniqueness and sequence across the union — then inserts and deletes rows mid-traversal, which is exactly where offset pagination skips and duplicates.
Review an AI-Generated OpenAPI Description Before You Publish It
Structural validity and truthfulness about a service are unrelated properties: a generated description parses, resolves and lints while inventing a DELETE endpoint and quietly making the refund route public. This guide starts with the security override that removes authentication in two characters of YAML, reconciles operations against a route inventory taken from the booted router, and shows why the specification's SHOULD on examples means nothing is obliged to reject an invented field.