ruk·si

API
Versioning

Updated at 2021-03-02 09:24

You should version your APIs for any non-trivial use-case. I prefer that the API consumers must specifically define which version they want to use.

HTTP API version is usually defined in the URL or request header. I prefer header a bit more as it's cleaner. URL can make more sense if required for request routing, but many load balancer do also support header based routing rules e.g. AWS Elastic Load Balancer.

Prefer semantic versioning. It's a good practice to add some logic to endpoint version numbering apart from a simple digit. API consumers can then understand that can they update to the new version without issues.

major.minor.patch
    major = includes breaking changes
    minor = new endpoints or parameters in the API but old calls work
    patch = internal changes but the API stays the same

Don't do project metaversions where you have a version for a set of service versions. This will lead microservices to become coupled and you lose many benefits of microservices.