API versioning is running more than one version of an API at the same time, so breaking changes can be released without affecting existing consumers. Versions are usually identified in the URL, such as /v2/, or in a request header.
Why it matters: Versioning lets an API evolve safely. Consumers can move to a new version when they're ready, instead of their applications breaking overnight.
In practice: Each live version needs its own tests. Teams keep a suite of tests per version and run them throughout the API's life, checking that each version still behaves as promised and that backward compatibility holds where it should.
Examples:
- Keeping tests for version 1 running while version 2 adds new required fields.
- Checking that a fix in version 2 hasn't changed version 1's responses.
Common pitfalls:
- Only testing the newest version, while most consumers are still on older ones.
- Making breaking changes inside an existing version instead of creating a new one.
When does an API need a new version? When a change would break existing consumers, such as removing a field, renaming an endpoint or changing a data type. Adding optional fields usually doesn't need a new version.
