So, you are new to this team. And in one of the bi-weekly tech leads’ meetings, one thing leads to another and you casually bring up how the error messages on all the APIs are not consistent. You hear one of the engineers telling you that their pull requests to update the core error handler have always been kept on hold and have never been merged. Before you could ask for more information, you hear a few other audible nods. All those have one thing in common, they are all breaking changes. Breaking, for the downstream systems and/or breaking for the clients that consume these resources. This discussion makes way for one of the commonly contested aspects of API development: “versioning”.

I think the topic of API versioning is probably as old as or older than the topic of URL design for applications themselves. And probably a discussion that most teams involved in API development get involved in. What makes it more interesting is the fact that there is no right answer or approach that fits all use cases. And thus makes up for quite an interesting conversation.

Why would you need to version your APIs?

A versioning strategy allows clients to continue using the existing API and migrate their applications to the newer API when they are ready. If you need to make breaking changes you might continue to do so and migrate to this new structure only when all the essential stakeholders are ready for it.

#api-management #hateoas #api-versioning #api #mvc