Glossary
API versioning
API versioning is the practice of exposing an API under an explicit version identifier so that a breaking change can be shipped alongside the existing behaviour instead of on top of it. Without one, every integration is built against whatever the API did on the day it was written, and the only way to change anything incompatibly is to break somebody. With one, the old behaviour keeps answering while integrators migrate on their own schedule.
Where the version goes
In the path, which is the most common choice and the easiest to see: the version is visible in every log line, every bug report and every browser address bar.
In the hostname, which separates the versions at the infrastructure level and allows them to be routed to different deployments.
In a request header, which keeps URLs stable at the cost of a version that is invisible unless someone inspects the request.
In a media type, which is the most protocol-faithful option and the least used, because tooling support for it is thin.
The choice matters less than making one. An API with no version anywhere has no way to change incompatibly at all.
What counts as a breaking change
Removing a field, renaming one, or changing its type. A client parsing the response will fail on all three.
Making an optional parameter required, or tightening validation on an existing one.
Changing the meaning of a status code, or returning a different one for the same condition.
Changing the default value of a parameter, which breaks clients that relied on the old default without ever naming it.
Adding an optional field is not breaking, provided clients ignore fields they do not recognise — which is a contract worth stating in the documentation.
What running two versions costs
Every version is code that must keep working, keep being tested and keep receiving security fixes.
The cost is not in shipping the second version; it is in the years afterwards, and it grows with each one that is never retired.
Which is why a deprecation policy matters as much as the versioning: a published date after which a version stops answering, announced long enough ahead to be acted on.
An API with four live versions and no retirement plan has four times the maintenance and one version's worth of value.
How it is observed
An explicit version in the observed API URLs or hostname is detected from the endpoints the site itself references.
A version carried only in a header is not visible from outside unless the site's own scripts send it, which is one practical argument for the path.
A published specification usually declares the version it describes, which is where an external reader looks next.
Absence of a detectable version is reported as information rather than as a defect, since a version may exist in a form an external observation cannot see.
Frequently asked questions
- Is a version in the path better than one in a header?
- It is more visible, which matters for debugging, logging and support. A header keeps URLs stable. Both work; having neither does not.
- Does adding a field break clients?
- It should not, if clients ignore unrecognised fields. That expectation belongs in your documentation, because a client that validates strictly will break on it.
- How long should an old version stay available?
- Long enough for integrators to migrate, announced with a date. The answer that causes trouble is no answer, because a version with no retirement date never gets retired.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website