Protocols
Saved & recent

API versioning

Also called: API compatibility, API evolution, backward compatibility

API versioning gives clients a way to select or identify a contract as that contract evolves. A version might appear in a path, request field or service definition. Versioning policy should explain compatibility, migration and retirement; a new label alone does not preserve old clients’ expectations.

In a hypothetical books API, renaming title to displayName can break existing readers. Keeping the old field while adding another may permit a gradual migration, if the documented compatibility rules allow it. Some providers expose major versions such as /v1/; others evolve a compatible interface. This is separate from choosing HTTP/2 or HTTP/3.

Related
OpenAPI, Protocol Buffers, HTTP/3
Further reading
old client new client transition server uses title uses displayName transition response title displayName API v1 · both fields separately versioned · displayName only HTTP version independent of contract hypothetical migration
This hypothetical policy first keeps both fields, then removes title under a changed contract. Even additive changes need compatibility rules. Selecting an API contract is separate from selecting HTTP/1.1, HTTP/2, or HTTP/3.

View in the full Protocols collection