API Versioning with Node.JS




 API versioning is one of the key concept when we consider API implementation. It's useful when we need to maintain coexistence of multiple versions of the API implementation. It happens when you need to enhance the functionalities and at the same time support existing API consumer which still rely on the current implementation. 

Typically, you do not need to maintain API versioning when the change can be gracefully handled by the application logic and the implementation won't result to any breaking change. Breaking change refers to implementation which affects the request or response of your existing API. API consumer can no longer consume the API as the API integration contract has been changed.    

Implementation of API versioning

There are many approaches can be used to handle API versioning. In generally, API service provider needs an indicator in API request to understand which version the API consumer need. I will cover two of the common approaches that you can use for your implementation; which are URL based versioning and Header based versioning. These 2 approaches have their pros and cons when they come to implementation. It depends on your requirement and which approach fit your needs. 

URL based versioning

As the name suggested, URL based versioning includes the version in API request URL. You may see a URL like https://example.com/api/v1/helloworld. This is a straightforward approach for API versioning. API consumer can easily identify the version by looking at the URL. With the version number includes in URL will also make it easy if you need to cache the API response. 

URL based versioning  is also easy to implement in Node.JS. To perform such implementation in threadfin-http, you basically create different handler JS file under the different version folders. In other web framework like Express.JS, you would need different routes and different route handler to manage the request.

Project Structure

In the above threadfin-http project, the "api_root" of my project is set to "handler". In handler folder, I created api/v1 and api/v2 folders. In the 2 folders, I created helloworld_handler.js which are the version 1 and version 2 implementation. 

version 1 helloworld_handler.js

Version 1 helloworld_handler.js is a simple implementation. It basically, return "Version 1 of Hello World" when you invoke the API. 


Version 2 helloworld_handler.js has similar logic. Instead of returning Version 1, I return "Version 2 of Hello World".

version 2 helloworld_handler.js


You may already noticed that Version 1 and Version 2 started to maintain 2 pieces of code. Any common implementation used by both handlers will need to be create as a common function and keep in separate JS file.


Header based versioning

Header based versioning leverages on HTTP header to keep the versioning. The custom header used to capture versioning is accept-version. As this is stored in HTTP header, we would need to implement a logic to retrieve the value from the header and then performs different logic based on the retrieved value. In threadfin-http, you can retrieve version by implementing setVersion function. threadfin-http will retrieve accept-version from header and use setVersion to set the value to a variable in process handler.

helloworld_handler.js using header based versioning


The advantage of this implementation is you continue to maintain same URL for the 2 versions of code. In addition, you do not need 2 process handler to keep the 2 implementations in threadfin-http. the 2 implementations are managed through a if condition. It will be easier if you need to maintain common logic within the same JS file. 
 
Result of version 1 hello world

Result of version 2 hello world


As I mentioned earlier, both approaches are viable and it really depends on your requirements. I hope you like my sharing and hope to share more in future !

Comments

Post a Comment

Popular posts from this blog

Build Retry-able API using idempotency key

Image
 If you have been working on API implementation for awhile and try to make your API resilient & bulletproof, the topic today might be something you will find interesting. Today, nobody can guarantee the microservices that you built will not run into trouble. When issue occurred, we often hope that the simplest way to solve the issue is to retry and invoke the API again. Retry can be an easy mechanism handled by your middleware/ API orchestration product. The challenge for doing so will always be on the business logic of the API if the nature of the record can gracefully managed the duplication through something like Primary Key. (e.g. create a car record with car registration number) You probably won't hit a problem when performing record update (if multiple updates is not a problem. e.g. update status of your car record from "available" to "sold"),  but it will be tricky for scenario of record creation.(e.g. create a sales record for a car) Making microserv...
Read more

Build a Batch Framework with Go

Image
Build a Batch Framework with Go Recently, I have just picked up Golang and decided to use what I learnt to build a Batch Framework with Go. Batch Framework - Batch103 I called this project Batch103 ( S tarted as Batch101. 103 is the 3rd version I decided to publish ) ; the project is a simple batch framework inspired by SpringBatch - a popular batch framework in Java world. If you familiar with SpringBatch, you may find many similar features you used to see in SpringBatch. The source code of the framework is available at github  (https://github.com/pengyeng/batch103.git )  I will illustrates the high level  architecture of Batch103 using a diagram. (Please refer the overall architecture diagram) The framework comes with a Job Launcher which provides  a implementation class to launch the batch job. Job Launcher needs 3 key components to operate; which are : Reader - handling the input of batch job Processor - handling the logic to process the data Writer - handling th...
Read more