API versioning
Giving an API contract a version so that incompatible changes can be released without breaking clients that use the old one.
In more detail
A version can live in the path (/v2/tasks), in a media type, or in a header; choose one clear place. Version only for breaking changes you are prepared to support and operate, not for every commit, and prefer additive changes that need no new version.
Related terms
- breaking change — A change that makes existing users of a program or interface stop working until they change something too.
- additive change — Evolving an API only by adding things, such as a new optional field or operation, while everything existing keeps its meaning.
- deprecation — Marking a feature as outdated and scheduled for removal, while it still works, so users have time to move to its replacement.
- backward compatibility — The property that a new version of an interface still works for clients written against the old one.
Taught in
- Versioning APIs — Modern API Architecture: REST, GraphQL & gRPC