API Contract Testing &
Schema Governance

Eighty-two production-focused guides on designing, validating, testing, versioning and governing API contracts across distributed systems — covering OpenAPI, AsyncAPI, Pact, JSON Schema, Zod, webhooks and auth.

📋 Contract Fundamentals 🔷 Schema & Validation

API contracts are the binding agreements between service producers and consumers — defining request and response payloads, status codes, error schemas, authentication requirements and behavioral guarantees. When engineering teams treat the contract as the single source of truth, they eliminate integration drift, enforce backward compatibility, and turn API quality into an automated gate rather than a review-time argument.

This site covers the full design-to-governance lifecycle across two areas and nineteen topics: choosing a specification format, verifying with consumer-driven contract tests, enforcing runtime validation, versioning and retiring endpoints without breaking live consumers, documenting outbound webhooks, and pinning the data representations — money, timestamps, 64-bit identifiers — that silently differ between languages.

The design to govern lifecycle, and where each topic sits Four stages run left to right: design the contract, validate payloads against it, gate changes in CI, and govern versions and deprecation over time. Each stage names the guides on this site that cover it. 1. Design choose the format 2. Validate enforce at the edge 3. Gate block breaking changes 4. Govern version and retire OpenAPI, AsyncAPI JSON Schema keywords data formats, webhooks Zod, Joi, Yup, Ajv error contracts mock servers Pact verification breaking-change diffs can-i-deploy gates versioning policy Sunset headers auth scopes, governance Every guide on this site belongs to one of these four stages.

Start Here

Writing your first contract

Model paths, components and security schemes in OpenAPI 3.1, then lint and bundle it in CI.

Stopping breaking changes

Diff every proposed contract against the last shipped one and block the merge when a live consumer would break.

Retiring an endpoint safely

Choose a versioning scheme, publish Sunset headers, run two versions side by side and retire by traffic.

Validating at the edge

Reject malformed payloads before business logic runs, with one schema shared by the browser and the server.

Pinning money and timestamps

Stop two services disagreeing about a total, a date or a 64-bit identifier by fixing the wire representation.

Publishing dependable webhooks

Sign every delivery, publish the retry schedule, and make at-least-once delivery safe for receivers.

Explore the Content

Choose a paradigm and a toolchain, run the design to govern lifecycle, gate breaking changes in CI, secure and version the surface, and publish webhooks consumers can depend on. Eleven topics.

View all →

Design payload schemas that hold: strict boundaries, runtime validation, generated types, error contracts, and the data representations that differ silently between languages. Eight topics.

View all →

Where the Failures Actually Happen

Contract defects cluster in a handful of places, and each one has a guide here. The diagram below maps the recurring production failure to the stage that should have caught it.

Recurring failures and the stage that prevents them Five production failures — a removed field, a duplicate webhook, a rounding mismatch, a silent identifier change and a permanent 403 — each traced to the lifecycle stage and the guide that addresses it. what breaks in production what should have caught it a response field disappears a customer is refunded twice two services disagree by a cent an identifier changes in the browser a partner gets a permanent 403 the breaking-change gate an idempotent webhook receiver money as integer minor units 64-bit ids transported as strings scope lists checked against the issuer