API versioning is an inevitable necessity, especially for long-lived and continuously evolving systems. When you update an API in a way that breaks backward compatibility, you must also consider existing clients. At this point, the most fundamental question we face is: Where should we place the version information? In this article, I will address the fine lines between the two most common approaches—URI-based versioning and Header-based versioning—using concrete examples from my own field experience.
While working on a production ERP system we developed, we needed to redesign the supply chain module. The existing APIs had to support legacy versions while seamlessly delivering new features. During this process, we deeply debated which versioning strategy would be more suitable for us. In this article, I will share the thought process behind this decision and the practical outcomes of both methods.
The Fundamental Importance and Emergence of API Versioning
The evolution of an API over its lifecycle is a natural process. New features are added, existing functionalities are improved, or security vulnerabilities are patched. However, these changes can pose risks for existing clients using the API. If a change breaks backward compatibility, existing clients may suddenly stop working. This situation causes disruptions in workflows and places a significant burden on the development team. This is exactly where API versioning comes into play.
