While developing the API, there is one reality that we should keep in mind, which is the principle of ‘Change is Inevitable’. Although we are carrying out business-oriented work during the development process, we may need to add more responsibilities to the API, either due to unpredictable or later needs. In such a case, we need to version the APIs as a result of each update, in order to be able to manage the effect of APIs on clients and to report the operational work performed, based on the changes made.
In fact, we can say that this requirement is the current manifestation of a software tradition. This tradition is the ‘Contract-Based Programming’, which is the contract design model (Design by contract). The contract-based programming approach, which was preferred a lot in the period of services such as -WebService / WCF- in the past, appears as a basic need in the process of modernizing today’s API technology and becomes a new basis with certain technical changes.
The Contract-Based Programming approach has a functionality that enables data transfer to take place in accordance with a contract placed between the client and the server.
Versioning has an essentially spatial need rather than traditional influences. This need is basically about the client-server relationship on physical updates in APIs. Changes made in APIs used by certain consumers will cause breakages / explosions for existing consumers. Therefore, the first factor to be considered in a change is the interruptions that may occur in the functional flows of those API consumers. In such a case, it is very useful to define the way clients interact with the API.
After the client’s relationship with the API and the data format structuring, if we come to the main question, ‘Why Do We Need to Version the APIs?’; As a result of each change made in an API, we need to inform the relevant client in order not to damage the relationship between the API and the client consuming that API. Here, versioning provides a sufficiently effective solution and informs the client as a result of only a small arithmetic operation on a numerical value in the url and allows the wheel to continue from where it left off.
In addition, versioning is carried out to report the changes made in the API and to emphasize the up-to-dateness of the API with reference to the latest change.
Example of API Versioning with Node.js
We versioned the REST API we created in a simple Node.js application as “v1”. The following codes belong to the application.
When we send a request to the v1 version of the application with Postman, we get the following response.
Now, let’s assume that there are some developments in the REST API and our response type has changed. Now REST API will return city information with country codes. Doing this in v1 will throw an error for apps parsing the REST API. Therefore, we will do this improvement in the v2 version. Now let’s update the “cityRoutes.js” file.
Let’s request the v2 version of the REST API we created with Postman.
As you can see, our API versioning process is working successfully.
Conclusion
Versioning is very important for large-scale projects. After you release your application to production, updates will continue to come out again, and performing these operations by versioning provides convenience and makes your project more manageable.
