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