Contract-First API Design

The spec is the source of truth. Code is generated from it — or validated against it. Never the other way around.

When to Activate

• Starting any new API endpoint, service interface, or event schema
• Adding or changing a contract between two services
• Detecting whether a change is breaking for consumers
• Setting up API CI pipelines (lint, validate, diff)
• Integrating Consumer-Driven Contract Testing (Pact)
• Replacing a code-first API with a proper contract

Core Principle