API Versioning – Using Date Released

While browsing Hacker News one day, my favorite news site, I came across Stripes versioning blog post. This was not the first time I had come across the idea of using dates to version your APIs, but this time I decided to give it a try.

Some Background

I’ve commonly seen others suggest simply putting version numbers in the URL to segregate major changes. This can work, but how often are major changes made to your API?

In my experience changes are typically updates to some of the returned data, or additional parameters required for precision. These are small changes but not always backward compatible.

If this happens somewhat often, you’ll be supporting many different versions simultaneously. Not only that, you’ll need to duplicate API endpoints that haven’t changed just to be part of these new versions.

Instead of duplicating the entire API to make some small changes, there is a way of just adding changes to the single endpoint. The following is mainly a proof of concept, but with some modifications it could definitely be a solution.

Using Dates to Access API Versions

So finally, I’ll get right to it. By utilizing the flexibility of the HTTP header we can send the date which our client is able to support. This is done by adding an API-Header with a value of let’s say ‘2017-02-10’.

By sending this date in the header, you’re saying that your client is compatible with all revisions prior to and including this date. If your client will always be up to date, simply use today’s date as the value.

Routing to Specific Versions of APIs

So now that you understand the client side, I’ll explain a little how the API routes the request. Express allows you to create multiple routers with different prefixes. The goal is to generate new routes based on timestamps of when the changes were done.

There is middleware in the express server that extracts the API-Version header value and converts it to a timestamp. The middleware then uses this timestamp to reroute the request to the version compatible with the timestamp. The following image will hopefully help explain.

Example of API Date Versioning Routing

You may be thinking, what happens when you release versions that don’t include changes to each endpoint. Well, in the same middleware the routing take place, it actually loops through the endpoints to find a matching url, such as ‘fn1’. The routers are obviously sorted in ascending order to match the latest one with the requested API version. But this way, if a version was not updated in the latest release that was requested, the latest updated version will be used.

It may be easier for some just to look at the code, so I’ve put together a quick project and threw it on GitHub. Check out my date-version-api project on GitHub. Let me know what you think.

API Blueprint – Mock Server

Mock Servers from API Specifications

Last week I mentioned an API specification called API Blueprint. Turns out not only does this allow us to document our API, but also use it.

That’s right, create a functioning mock server from that same API Blueprint used to document your API. I did mention this a bit in my previous post but I thought I’d put together a quick example.

Install Drakov

sudo npm install -g drakov

I just grabbed the Polls API example from the blueprint examples.

I renamed the file to have a .apib extension. Run drakov like the following:

drakov -f PollsAPI.apib

Now you can access a mock server to test your front end code with! See the picture below for example.


Drakov Tips

If you’re running the mock server on a different host and from a browser, be sure to enable  OPTIONS. To do this use the –autoOptions argument. This is because when the browser is accessing another host it will send a pre-flight OPTIONS request to see if the intended request is allowed. This bit me when creating my first NodeJS Express applications, I will always remember, vividly.

Use Notepad++ to find and replace tabs in your API Blueprint. Drakov can’t parse blueprints with tabs 🙁 .


API Specification – API Blueprint

What’s an API Blueprint?

An API Blueprint is actually a specification used to describe an API. Its source is a markdown file using plain text formatting. The specification enables a software developer/architect/whatever to use their documents with other applications/tools that adhere to the same specification.

What’s so special about using a specification?

You actually create a document based on a specification. This way, both humans and software can read it. Since it follows a common format/structure, software can parse these documents and use the contents. The contents can be used for some things such as documentation and mock servers.

Why bother making an API Blueprint?

It may seem like it’s just a lot of additional work, but it can save development time drastically. Real example, I had introduced this blueprint idea at work and decided to go ahead and build it. I had not even started programming this API yet but I created the blueprint for what my fellow coworker and I agreed on should be included in the API.

From this, I used a NodeJS tool called Drakov to create a mock server. While I was busy working on a separate application. My coworker was able to program his application using the mock server just like he would a server in production. The responses can be somewhat limited, but can easily be modified.

Not only was this great because he didn’t need to wait for me to program the API for his testing. But we found changes that needed to be made to the API for his application to function as desired. We were able to make a solid API design without rewriting any parts of the API while the client application was being built.

Documentation was mentioned…

Yes, the documentation aspect is wonderful. I think source documentation is underrated, but API documentation is a necessity. I used a tool called aglio to generate documentation for the API. Using the same markdown file (API Blueprint) created for the mock server, aglio generates its documentation. Check this example out from aglio below.

API Blueprint aglio example

This is the cyborg theme which looks pretty cool IMO. In the generating of the documentation, no html is needed. You can however use HTML to manipulate the icons and some styles.

Another thing worth mentioning. When using aglio to generate the documentation, it will also generate the response schema. This is a description of the object being returned. You can also use this schema to validate your json responses, also in unit testing! I’ll get to that another time…

I hope you found this post informative! If you have any tools you’d like to share please leave a comment. Maybe even a new parser or theme for API documentation, please share.