Learning Resources
This module is populated from the local chunked books in library/raw/semester-07-architecture-ddd/books. Use this page as a source map, not as an instruction to read everything.
Source Stack
| Book | Role | How to use it in this module |
|---|---|---|
| API Design Patterns (JJ Geewax) | Primary teaching source | Default escalation for resource modeling, standard methods, custom methods, LRO, batch, pagination, filtering, versioning, and deprecation |
| Fundamentals of Software Architecture (Richards & Ford) | Selective support | APIs as architectural surfaces, event-driven architecture style, monolithic vs distributed tradeoffs |
| Learning Domain-Driven Design (Khononov) | Selective support | Bounded contexts and integration patterns (Open Host Service, Published Language, Anticorruption Layer), event-driven architecture |
| Clean Architecture (Martin) | Optional | Boundary discipline between layers and services |
| Just Enough Software Architecture (Fairbanks) | Peripheral | Modeling vocabulary and architecture description |
Resource Map by Cluster
Cluster 1: API as a Product
| Need | Best local chunk | Why |
|---|---|---|
| what an API is, "good" criteria | Geewax: What are web APIs? | Opens the whole discussion |
| resource-oriented framing | Geewax: What are resource-oriented APIs? | Core mental model for Cluster 2 as well |
| operational, expressive, simple | Geewax: Expressive and simple | DX criteria made concrete |
| predictability | Geewax: Predictable | The fourth "good" property |
| pattern vocabulary | Geewax: What are API design patterns? | Grounds the "design pattern" language |
| why patterns matter | Geewax: Why are API design patterns important? | Governance / consistency rationale |
| naming | Geewax: What makes a name good | Consistency begins here |
| case study of bad naming | Geewax: Bad names case study | Makes consistency costs visible |
| APIs as an architectural surface | Fundamentals of Software Architecture: Defining software architecture | Helps frame APIs at the architecture level |
Cluster 2: HTTP/REST Resource Design
| Need | Best local chunk | Why |
|---|---|---|
| resource layout | Geewax: What is resource layout? | Starting model for URLs |
| relationship types | Geewax: Types of relationships | 1:1, 1:N, N:N and implications |
| ERD and relationship necessity | Geewax: Entity relationships | When relationships don't belong in the API |
| reference vs inline, anti-patterns | Geewax: References vs inline | Common anti-patterns to avoid |
| anti-patterns: resources for everything | Geewax: Anti-patterns | The two failure modes of resource modeling |
| standard methods - overview | Geewax: Which methods, idempotence, GET | Verb discipline |
| List | Geewax: List | List-method contract |
| Create and Update | Geewax: Create and update | POST / PUT / PATCH details |
| Delete | Geewax: Delete | Delete semantics and tradeoffs |
| partial updates | Geewax: Partial update motivation | When PATCH is the right answer |
| page size | Geewax: Page size | Bounding responses |
| page tokens | Geewax: Page tokens | Cursor-based pagination |
| offsets-and-limits anti-pattern | Geewax: Total count, offsets-limits anti-pattern | Why offset paging is wrong default |
| filter structure | Geewax: Filtering structure | Designing filter param shape |
| filter syntax part 1 | Geewax: Filter syntax 1 | Expression grammar |
| filter syntax part 2 | Geewax: Filter syntax 2 | Operators and behaviors |
| filter syntax part 3, tradeoffs | Geewax: Filter syntax 3 and tradeoffs | Closing the filtering discussion |
Cluster 3: Beyond CRUD - Actions, Events, and Async Patterns
| Need | Best local chunk | Why |
|---|---|---|
| custom methods motivation | Geewax: Custom methods motivation | Why CRUD does not fit |
| custom methods overview | Geewax: Overview, side effects | The :verb pattern and its rules |
| custom methods on collections | Geewax: Resources vs collections, tradeoffs | Collection-level actions |
| LRO motivation | Geewax: LRO motivation | Why async contract matters |
| LRO overview | Geewax: LRO overview | What an LRO looks like |
| LRO resolution | Geewax: LRO resolution | Completion semantics |
| LRO errors and monitoring | Geewax: Error handling and monitoring | How clients observe progress |
| LRO cancel, explore | Geewax: Canceling and exploring | Full LRO lifecycle |
| rerunnable jobs | Geewax: Rerunnable jobs | Jobs as first-class resources |
| batch motivation | Geewax: Batch - collective operations | Why batches are a distinct pattern |
| batch atomicity | Geewax: Batch atomicity | The hardest batch decision |
| batch operations (get, create, update) | Geewax: Batch get, batch create | Mechanics per batch flavor |
| import / export | Geewax: Import-export | File-based bulk pattern |
| import/export consistency | Geewax: Consistency, ids, relatives | Non-obvious file-pattern contracts |
| request deduplication / idempotency | Geewax: Request deduplication | Central to webhook consumers and retries |
| retries - back-off | Geewax: Exponential back-off | Retry policy discipline |
| retries - Retry-After | Geewax: Retry-After, tradeoffs | Server-guided retry behavior |
Cluster 4: RPC, GraphQL, and Event-Driven APIs
| Need | Best local chunk | Why |
|---|---|---|
| RPC vs resource-oriented framing | Geewax: What are web APIs? (revisit) | Grounds the RPC/REST contrast |
| distributed architecture context | Fundamentals of Software Architecture: Monolithic vs distributed | Where RPC/GraphQL/events fit in topology |
| event-driven style | Fundamentals of Software Architecture: EDA style | Mediator vs broker topology |
| event-driven architecture in DDD | Learning DDD: Event-driven architecture | Domain-level framing for events |
| types of events | Learning DDD: Types of events | Notification vs state-carried, and the failure mode |
| bounded contexts and integration | Learning DDD: Cooperation to conformist | Partnership, customer-supplier, conformist |
| anticorruption layer | Learning DDD: Anticorruption layer | When consuming an API you do not control |
| model translation | Learning DDD: Model translation | Translating published languages |
Cluster 5: Versioning, Deprecation, Compatibility
| Need | Best local chunk | Why |
|---|---|---|
| compatibility definition | Geewax: What is compatibility? | Establishes the vocabulary |
| defining backward compat, part 1 | Geewax: Backward compatibility 1 | Concrete rules begin here |
| defining backward compat, part 2 | Geewax: Backward compatibility 2 | Subtle cases |
| defining backward compat, part 3 | Geewax: Backward compatibility 3 + implementation | Implementation patterns |
| perpetual stability | Geewax: Perpetual stability | One stance on versioning |
| agile instability | Geewax: Agile instability | The opposite stance |
| semantic versioning | Geewax: Semantic versioning and tradeoffs | Middle ground, library-like |
| versioning tradeoffs | Geewax: Granularity vs simplicity | Choosing version granularity |
| deprecation and ubiquity | Geewax: Happiness vs ubiquity | Rollout pragmatics |
| soft delete motivation | Geewax: Soft deletion motivation | Soft deletion pattern for resources |
| deleted designation | Geewax: Deleted designation | Marking deletion on resources |
| expunging and effects | Geewax: Expunging | Hard removal after soft-delete |
| soft delete across versions | Geewax: Soft delete across versions, tradeoffs | Introducing deprecation in a live API |
Exercise Support Chunks
Use these when concept pages are understood but you need pattern volume:
- Geewax: Request validation
- Geewax: Resource revisions
- Geewax: Revision identifiers
- Geewax: Request retrial
- Geewax: Request authentication
- Geewax: Polymorphism - structure
- Geewax: Cross references
External Resources (Read-If-Curious)
Only use these if you want a second exposition or a supplementary problem source. The module is completable from the local chunks alone.
- Google Cloud API Design Guide - widely cited reference style guide; the modern anchor for REST-ish design at scale.
- Google AIP (API Improvement Proposals) - the rules Google follows internally; short numbered docs.
- Microsoft REST API Guidelines - industry-standard counterpart to Google's guide.
- Stoplight API Design Guide - accessible, pragmatic REST guidance.
- API Evangelist - long-running writing on API strategy and governance.
- JSON:API Specification - one opinionated answer to "what should my response envelope look like?"
- RFC 7807 - Problem Details for HTTP APIs - error format reference.
- RFC 8594 - Sunset HTTP Header - sunset signalling.
- RFC 9745 - Deprecation HTTP Header - deprecation signalling.
- OpenAPI Specification - industry-standard REST spec format.
- gRPC documentation - canonical introduction.
- JSON-RPC 2.0 Specification - whole spec is short; read it.
- GraphQL Introduction - canonical introduction to schemas, queries, mutations.
- GraphQL Best Practices - short, authoritative.
- Principled GraphQL (Apollo) - operational guidance.
- AsyncAPI Specification - canonical spec for event-driven contracts.
- CloudEvents Specification - portable event envelope.
- Stripe API Reference - a live example of date-based header versioning done well.
Use Rules
- If you are stuck on resource modeling or URL design, go to Geewax Cluster 2 chunks first.
- If you need versioning rigor, go to Geewax chunks 101-109.
- If you need event-driven framing (not just transport), use Learning DDD and Fundamentals of Software Architecture.
- Open one chunk for one gap; do not wander through a whole chapter sequence by default.
- External URLs are reference material, not a reading list. Google API Design Guide can replace half this module's content - but reading it cover-to-cover is not required.