liveBook · Manning

Versioning

As explained in Grokking Software Architecture

Version control is the systematic management of changing files and their history so changes can be reviewed, reproduced, and restored.

An API is a public contract: clients may depend on behaviors you never documented. Versioning lets you change that contract without breaking clients that still rely on the old one. section 6.12 section 6.3.4

Keep both menus open

A new orders format can live at GET /api/v2/orders while existing clients continue using GET /api/v1/orders. For a gradual alternative, clients can send a release-date header, such as Stripe-Version: 2024-09-14, to the same endpoint. Date-based versioning eases client migrations but adds server-side translation complexity. section 6.3.5

Choose an approach to fit the API:

  • Use URI path versioning for internal services or smaller public APIs. section 6.3.5
  • Consider date-based versioning when incremental updates for public consumers justify maintaining compatibility transformations. section 6.3.5

How Grokking Software Architecture covers it

How deep it goes
Compares URI-path and date-based strategies, examples, and tradeoffs without detailing implementation steps.
Examples
Shows v1 and v2 order endpoints and a Stripe release-date header.
What you can do after
Evaluate versioning approaches by client migration needs and server-side complexity.
How it connects
Links API versioning to public contracts, client compatibility, and API gateways.

Also explained in

Compare how 36 books explain versioning →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.