API Versioning

As axioms go, few are more true than "The only constant is change." The earth makes one revolution, and things change. Life cyles begin and end. What was relevant yesterday, may matter no more today.

Business needs constantly change. Regulatory environment, competitor innovation, and market demands can each have a transforming effect on business. IT must respond to changing business requirements that are sometimes unpredictable and arbitrary.

IT serves business. An API designed to fulfill today's requirement may tomorrow be insufficient, or even woefully inadequate. So how can an API be designed to both serve specific, immediate requirements while recognizing and taking into account the unknowns that change will bring over time?

One way would be to construct an RPC style API that meets the exact need and denote it with a granular version designation. Then, when change arrives, handle it directly by adding an endpoint and incrementing the granular version designation appropriately. This approach has drawbacks, such as massive proliferation of endpoints to maintain.

In the OneClickdigital API we have made the choice to follow a "versionless" style of API. We will maintain existing API contracts & functionality, while handling change through additions, as opposed to modifications to existing API code and contracts. This loosely follows the "Open Closed Principal" found in SOLID.

Even though a versionless, open to extension, closed to change approach will be employed in our attempt to handle changing requirements, the OneClickdigital API does incorporate a major version number "V1" which is found in the base URL. It is a fallback intended to accommodate modifications to the API on a macro scale should the need ever arise.