API Contracts First: Designing Service Boundaries Before Writing Code

API-first is the A in MACH — but most teams treat it as a documentation step, not a design step. This post makes the case for contract definition as the first deliverable of any new service.

What API-First Actually Means

API-first means the contract is the product. Before you write a line of implementation code, the API specification is reviewed, versioned, and agreed upon by both the producing and consuming teams.

OpenAPI as a Design Artifact

Too many teams generate OpenAPI specs from code. This is backwards. The spec should be written first, reviewed like any design document, and used to generate server stubs and client SDKs.

Consumer-Driven Contract Testing with Pact

Pact lets consumers define what they expect from a provider. The provider then verifies it can meet those expectations. This catches breaking changes before they reach production — without requiring full integration tests.

The Team Workflow: Contract PR Before Implementation PR

Make it a rule: no implementation PR is opened until the contract PR is merged. This forces design discussions to happen at the boundary — where mistakes are most expensive if caught late.