Let's Build an API together - Part 5

Last Update: 19.12.2017. By Jens in API Series | APIs | Newsletter

The next thing we should consider in building our API is a versioning scheme. It is inevitable that we are going to change an API and at some point will face backward-incompatible changes. You might ignore it if you only have one client. But trust me, if you don’t consider it from the start, it will ruin your day in the future.

It sounds more complicated than it actually is. Basically, we just need a version ID somewhere in the full URL of our endpoints. Two classics you can use:

• Make it part of the host, i.e. http://my-api-v1.example.com
• Make it part of the path, i.e., http://api.example.com/v1/

The big question left is, when do we use a new version?

When you make backward-incompatible changes like refactoring entities or if the behavior of your API is massively different in how it handles functionality.

When you extend entities with new fields, you can keep the same version. Basically, you can change anything that is backward-compatible with creating a new version.