Metadata Card
- Prerequisites: Chapter 14 (Microservices Patterns); HTTP basics
- Estimated Time: 45 minutes
- Core Difficulty: Intermediate
- Completion Milestone: Design RESTful API contracts, use OpenAPI, implement consumer-driven contract tests
Your Progress
The City of Artisans workshops have been split into independent studios: Forge Studio, Assembly Studio, Sharpening Studio. Each can independently supply parts. But the problem: when another studio borrows tools or requests parts, there's no standard interface. Forge Studio says "steel ingot code 4032"; Assembly Studio calls the same thing "main support raw material." Wrong parts arrive, delaying the project by three days.
Each studio is a service. Services need contracts — a mutually agreed interface definition. Your Task
When a system grows from monolith to multiple services, you need precise definitions of service capabilities, inputs, outputs, and error handling.
Required reading: REST resource modeling, versioning strategies, OpenAPI basics Selective: gRPC/AsyncAPI comparison Advanced: Consumer-driven contract tests
First Layer: Why Contracts Matter
API contracts are signed interface specifications: what resources, what methods, input/output format, error format, version change rules.
OpenAPI for REST, Protobuf for gRPC, AsyncAPI for events.
Second Layer: Resource Modeling & HTTP Semantics
Resources = nouns. GET /parts (collection), GET /parts/{id} (singleton). HTTP methods: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE.
Third Layer: Versioning
URI versioning (/v1/) or Header versioning (Accept: application/vnd.forge.v2+json). Compatible changes (new fields, new optional params) don't need major version.
Fourth Layer: Idempotency, Pagination, Filtering
Idempotency key prevents duplicate requests. Cursor-based pagination for large datasets. Server-side filtering.
Fifth Layer: Consumer-Driven Contract Tests (CDCT)
Consumers define the contract. Providers verify they satisfy it. "Contract first, implement second."
Common Pitfalls: All errors return 200 with business code, no versioning, pagination done in application layer (not SQL), contracts only in developers' heads.
Traveler's Notes
API contracts transform you from "guess-the-interface workshop" to "standard-catalog guild." Resource modeling defines data shape, versioning enables evolution, idempotency prevents duplicate processing, and unified error model means callers never guess the JSON structure.
Next: Domain-Driven Design (Chapter 20).