API Versioning Strategies

When an API must support incompatible contracts, consumers need a reliable way to select the one they understand. A versioning strategy defines that selection and the promises attached to it. Adding /v2 to a URL is only one part of the design.

This chapter compares common HTTP API versioning strategies and explains how to choose among them. A fictional order API illustrates the trade-offs, including version labels, defaults, error handling, caching, and the implementation the service needs to serve multiple contracts accurately.