How and why I built Express-api-versioning

About me

I am a software developer with over 6 years experience and an entrepreneur. I am the CEO/Co-founder at Multi Server Network, MSN Academy and Instutory. I dedicate my expertise to solving practical problems in the society.

I started my career as a PHP Developer 6 years ago and I recently started working with Javascript this year.

I am passionate about programming, kids and helping people. I am working on a TV show that aims to discuss salient issues as it affect the youths.

I tweet @adesege_.

The problem I wanted to solve

I was working on a project which requires versioning my api; something like /api/v1, /api/v2. Most implementations I found online didn't do what I wanted.

I needed a way to dynamically route between different api versions without me having to tightly couple my api endpoints into my application.

I also needed to have a simple way to organize my api folders so I can easily seperate version one from version two, for example.

What is Express API Versioning?

Express API versioning is an express middleware that dynamically loads different API versions seamlessly depending on the version number specified in the request url.

It is written in Javascript ES6 syntax and it is further transpiled down to Javascript ES5 using babel.

I recently released version 2 which introduced a new way to resolve errors using callback instead of the try and catch block in version 1.

Tech stack

Express is required as a peer dependency, of course.

The process of building Express API Versioning

I needed to have a well defined folder structure. So the first thing was for me to plan how the folder structure would be and how resources would be shared between my application entry point and apis.

So, I came up with this, for example:

    api/
        v1/
          controllers/
          ....
          seeders/
          app.js
        v2/
          controllers/
          ....
          models/
          app.js
    express.js

I have an api folder which contains all the different api versions my application has in folders. Each folders are independent of each other except you want to require a module from v1 in v2.

Also, each folders have an entry point called app.js. Because, we have to use a single instance of express in our application, each version entry points exports a function which takes an instance of express as parameter. So you can easily use the instance in each entry point.

express.js, which is in the same root with the api folder, is where we instantiate express and pass it on to express-api-versioning for use in our entry point.

The beauty is that you can also use it to load your client application.

Here is an example implementation

Challenges I faced

This was my first NPM package and I had little knowledge on how to publish an NPM package. It was challenging at first but after reading some tutorials online, I was able to overcome it.

Key learnings

In version 1, I thought it was just fine throwing an error and allowing the user catch it in their application but then, I realised it doesn't sound node like.

Also, I haven't seen any package or express middleware throw an error to the user. Instead, they send the error to a callback and allow the user do whatever they like with it.

In version 2, I implemented an higher order function to enable users handle the error the way they like.

Resources

• I have written a well detailed documention in the package readme here
• Repository link: https://github.com/adesege/express-api-versioning

Want to contribute?

Thank you for your interest in contributing. I currently accept contributions from everyone. Please see the contributing guide for more details.