Skip to main content

Versioning Strategies: URL, Header, Content Negotiation

This generated surface maps a learner-facing curriculum unit to its canonical source routes.

Curriculum surface​

  • Open learner-facing unit
  • Curriculum path: content/curriculum/architecture/semester-07-architecture-ddd/module-04-api-design-contract-evolution/concepts/cluster-05-versioning-deprecation-compatibility/14-versioning-strategies-url-header-content-negotiation-primary.md
  • App: architecture
  • Semester: semester-07-architecture-ddd
  • Module: module-04-api-design-contract-evolution
  • Unit kind: concept
  • Curation level: module_curated

Learning objectives​

  • Explain Versioning Strategies: URL, Header, Content Negotiation as a contract and evolution problem, not just an endpoint-shape or schema-format decision.
  • Use Versioning Strategies: URL, Header, Content Negotiation to reason about compatibility, versioning, lifecycle cost, and the blast radius of public interfaces.
  • Use api-design-patterns to connect the learner page to contract design, compatibility strategy, and API governance decisions.

Prerequisites​

  • Comfort with modular boundaries and bounded contexts, because APIs are where those boundaries become explicit contracts.

Source books​

  • api-design-patterns

Source routes​

Api Design Patterns​

  • /books/api-design-patterns via Geewax: Agile instability, Geewax: Granularity vs simplicity, stability vs new functionality, Geewax: Happiness vs ubiquity, Geewax: Perpetual stability, Geewax: Semantic versioning and tradeoffs

Supporting curriculum routes​

No supporting curriculum routes linked yet.

External enrichment​

  • Microsoft REST API Guidelines (official_docs_companion) - Useful when the learner needs a concrete, opinionated guideline set for real public API design decisions.
  • Zalando RESTful API Guidelines (optional_deep_dive) - Provides another mature production perspective on compatibility, lifecycle, and API governance.

AI companion modes​

  • Explain simply
  • Socratic tutor
  • Challenge my understanding
  • Diagnose my confusion
  • Connect forward / backward

Source-of-truth note​

This teaching unit is learner-facing guidance. Its canonical source backbone is the referenced book api-design-patterns, and outside material should only clarify or strengthen that backbone.