Module 4: API Design & Contract Evolution

Primary text: API Design Patterns (JJ Geewax)
Selective support: Fundamentals of Software Architecture for APIs as architectural surfaces, Learning Domain-Driven Design for integration across bounded contexts, Clean Architecture for boundary discipline, Just Enough Software Architecture for peripheral framing

This guide is the primary teacher. You do not need to read the source books front-to-back. You do need to leave this module able to design a non-trivial HTTP/REST API, critique a gRPC or GraphQL alternative, and evolve a live contract without breaking consumers.

---

Scope of This Module

API design is where your architecture meets other people's code. Every decision is a contract, and contracts are expensive to break.

What it covers in depth:

• what an API contract actually is, and how consumers read it
• developer experience as a design force: errors, docs, consistency
• API governance: ownership, standards, review practice
• REST resource modeling: nouns, plurals, hierarchies, anti-patterns
• HTTP verbs, status codes, and idempotency semantics
• pagination, filtering, sorting, and partial responses
• custom actions when CRUD does not fit
• long-running operations, webhooks, and async callbacks
• batch, streaming, and bulk patterns
• RPC styles (gRPC, JSON-RPC) and when they beat REST
• GraphQL: schema-first, over-fetching, N+1 concerns
• AsyncAPI and event-driven contracts
• backward and forward compatibility rules you can actually enforce
• versioning strategies: URL, header, content negotiation
• deprecation policy and sunset discipline

What it deliberately does not cover:

• authentication protocols in depth (touched, but full coverage is in S9)
• API gateway and service mesh configuration (S8)
• full OpenAPI specification authoring (linked only)
• service discovery and cross-cluster routing (S8 / S9)

---

Before You Start

Answer closed-book:

1. What is the difference between an API's contract and its implementation? Which one are consumers coupled to?
2. Name three reasons a team would choose POST /orders/{id}:cancel over DELETE /orders/{id}.
3. What does it mean for an HTTP method to be idempotent? Which of GET, POST, PUT, PATCH, DELETE are idempotent by spec?
4. How would you paginate a list of 10 million rows without skipping or double-returning items when writes happen concurrently?
5. What is a breaking change to a JSON response, and what is a non-breaking change?

Diagnostic Interpretation

4-5 solid answers - Ready for the full path.
2-3 solid answers - Continue, but expect extra time in Clusters 2 and 5.
0-1 solid answers - Re-read S7M3 bounded contexts briefly; API boundaries are useless without domain boundaries.

---

What This Module Is For

Most engineering teams ship APIs long before they ship architecture. The APIs become the architecture. Throughout the program you will be asked:

• can we add this feature without breaking any client?
• why did our "simple REST API" end up with 47 custom endpoints?
• should this integration be REST, gRPC, GraphQL, or events?
• how do we deprecate v1 when some consumers have not called us in months?
• why is our error format different on every endpoint?

This module builds the design reasoning needed for:

• microservice contracts (S8M2)
• CI/CD for API deployments with contract tests (S9M4)
• architecture decision records about integration style (S7M5)
• distributed-systems consistency discussions from S6

---

Concept Map

---

How To Use This Module

Work in order. Cluster 5 (versioning) only makes sense after you have modeled resources and verbs in Clusters 2-3.

Cluster 1: API as a Product

Order	Concept	Type	Focus
1	What an API Contract Is and Who It Is For	PRIMARY	Contract vs implementation, consumers as users
2	The Developer Experience Lens: Errors, Docs, Consistency	PRIMARY	DX as a first-class quality attribute
3	API Governance: Ownership, Standards, Review Process	SUPPORTING	How consistency survives 50 services and 200 engineers

Cluster mastery check: Can you explain what your API promises to its consumers in one paragraph, and name who reviews changes to that promise?

Cluster 2: HTTP/REST Resource Design

Order	Concept	Type	Focus
4	Resources and URL Design: Nouns, Plurals, Hierarchy	PRIMARY	Modeling resources, picking hierarchies, avoiding pitfalls
5	HTTP Verbs, Status Codes, and Idempotency	PRIMARY	Verb semantics, status-code discipline, safety classes
6	Pagination, Filtering, Sorting, and Partial Responses	PRIMARY	Cursor vs offset, filter languages, sparse fields

Cluster mastery check: Given an unfamiliar domain, can you sketch a 10-endpoint REST API with correct verbs, status codes, and a pagination scheme that survives concurrent writes?

Cluster 3: Beyond CRUD - Actions, Events, and Async Patterns

Order	Concept	Type	Focus
7	Custom Actions: When CRUD Does Not Fit	PRIMARY	Named methods on resources, :verb patterns, side effects
8	Long-Running Operations, Webhooks, and Async Callbacks	PRIMARY	LRO resources, polling vs webhook, delivery guarantees
9	Batch Operations, Streaming, and Bulk Patterns	SUPPORTING	Batch atomicity, import/export, streaming responses

Cluster mastery check: Can you choose between a custom action, an LRO, a webhook, and a batch call for a given feature, and defend the choice?

Cluster 4: RPC, GraphQL, and Event-Driven APIs

Order	Concept	Type	Focus
10	RPC Styles: gRPC, JSON-RPC, and When to Prefer Them	PRIMARY	Contract-first schemas, streaming, internal vs external
11	GraphQL: Schema-First, Over-fetching, N+1 Concerns	PRIMARY	Query language, resolver patterns, operational costs
12	AsyncAPI and Event-Driven Contracts	SUPPORTING	Describing topics, payloads, and compatibility for events

Cluster mastery check: For a new integration between two teams, can you pick REST, gRPC, GraphQL, or event-driven and write a one-paragraph justification grounded in traffic shape, tooling, and consumer profile?

Cluster 5: Versioning, Deprecation, and Compatibility

Order	Concept	Type	Focus
13	Backward- and Forward-Compatibility Rules	PRIMARY	What is and is not a breaking change
14	Versioning Strategies: URL, Header, Content Negotiation	PRIMARY	Picking one strategy and living with it
15	Deprecation Policy and Sunset Discipline	PRIMARY	Deprecation / Sunset headers, announcements, removals

Cluster mastery check: Given an API at v1 and a required change, can you state whether it is breaking, choose whether to introduce v2, and write the deprecation plan?

Then work these practice pages:

Order	Practice path	Focus
1	REST API Design Workshop	Resource modeling, verbs, pagination, filtering
2	Integration Style Clinic	REST vs gRPC vs GraphQL vs events, tradeoffs
3	Evolution and Compatibility Lab	Diff two specs, classify changes, plan the migration
4	Code Katas	Timed design-and-defend drills

Use Module Quiz after the concept and practice path. Use Reference and Selective Reading and Learning Resources for targeted reinforcement.

---

Learning Objectives

By the end of this module you should be able to:

1. Explain what an API contract is, name its audience, and distinguish it from implementation detail.
2. Evaluate the developer experience of an API against concrete criteria: error model, consistency, discoverability, failure documentation.
3. Design REST resource hierarchies with correct nouns, plurals, and relationships; identify the three worst anti-patterns when you see them.
4. Pick HTTP verbs and status codes with correct semantics, and defend idempotency claims with code-level reasoning.
5. Choose a pagination scheme (offset, cursor, keyset) appropriate to the data and workload, and defend the choice.
6. Decide when to use a custom action, an LRO, a webhook, or a batch call, rather than forcing CRUD.
7. Describe the tradeoffs between REST, gRPC, GraphQL, and event-driven APIs in operational, tooling, and consumer terms.
8. Classify any proposed change as backward-compatible, forward-compatible, or breaking, with a written justification against the wire format.
9. Apply a versioning strategy consistently (URL, header, or content negotiation) and defend it against the alternatives.
10. Write a deprecation plan with announcement, Sunset header, dual-running window, and removal criteria.

---

Outputs

• one full REST API design (at least 12 endpoints) for a domain from S7M3, in OpenAPI 3.1, with written design notes
• the same API restated as a gRPC service and as a GraphQL schema, with a comparison memo
• a pagination decision record naming the scheme, the reasoning, and what breaks it
• a compatibility checklist you can run against any proposed change to a contract
• a deprecation playbook template (announce -> dual-run -> Sunset -> remove) with at least one worked example
• an integration-style decision log: for at least 6 integrations, REST/gRPC/GraphQL/event chosen with justification
• a mistake journal naming at least 8 recurring API-design errors (GET with body, overloading POST, versioning-by-copying-controllers, inconsistent error shapes, etc.)

---

Completion Standard

You have completed Module 4 when all of these are true:

• you can design a non-trivial REST API from a domain model in under an hour and defend the result
• you can state which proposed changes to your API are breaking without running a tool
• you have written and reviewed at least one OpenAPI spec end-to-end
• you have a deprecation playbook you could hand to a junior engineer and expect correct behaviour
• you can pick an integration style for a new feature and defend the choice against at least two alternatives
• you have designed one API as REST and as gRPC side-by-side, and can articulate why you chose the one you shipped

If your API "works in Postman" but you cannot say which of its fields are promised to consumers, the module is not complete.

---

Reading Policy

• Concept pages are the main path.
• Local book chunks from API Design Patterns are the primary selective reinforcement.
• External URLs (Google Cloud API Design Guide, Microsoft REST API Guidelines, graphql.org/learn, grpc.io, asyncapi.com) are permitted and cited in resources.md.
• Read only if stuck means try the concept page, self-check, and drill first.
• Written spec excerpts (OpenAPI YAML, proto, GraphQL SDL) are required deliverables, not optional enrichment.

---

Suggested Weekly Flow

Day	Work
1	Concepts 1-3, write a one-paragraph contract for an API you already use
2	Concepts 4-5, sketch resources and verb table for one domain
3	Concept 6, implement pagination + filtering on the sketch
4	Concepts 7-8, draft LRO and webhook endpoints for the sketch
5	Concept 9, add batch operations with explicit atomicity contract
6	Concepts 10-11, restate the API as gRPC and as GraphQL
7	Concept 12 and Practice 1
8	Concepts 13-14, diff v1 and proposed v2, classify every change
9	Concept 15 and Practice 2 + 3
10	Practice 4, quiz, deprecation-playbook review

---

Reference

If you need exact links into the local chunked books, use Reference and Selective Reading.

---

Build Your Own X - elective

The Web Server tutorial builds HTTP from scratch and forces explicit API contract decisions. Pair it with Redis Server when you want a compact command-protocol case study: framing, arity errors, pipelining, slow clients, compatibility, and versioned behavior. See Build Your Own X overview.

Rich Learning Pages

Worked Examples | Guided Labs | Case Studies | Mistake Clinic | Reading Guide | Capstone Thread

---

Model Artifact Calibration

For contract governance evidence, compare your policy to the API evolution/deprecation model artifact.