Thursday, May 8, 2014

Versioning your API

Who has not written or used an API? If you answered no, then this article is not for you and honestly I question how you ended up here. APIs are all the rage these days and everyone has an opinion on what an API should look like. Even more controversial is how do you version your API.

It depends on what you believe.

1. Do you believe in Roy Fielding's REST architecture?
2. Do you believe that accept headers describe how you'd like the resource returned?

If you subscribe to REST (and not Rails version of REST), then you acknowledge that the URL is a permalink to a resource. A location where that resource can always be found. Specifying a version number in that URL suggests that each version is an entirely different resource, not the the same resource presented differently.

And just as the semantics of HTTP verbs make sense, so the semantics of HTTP headers. In the request header I am describing how I want my resource returned. Do I want it returned as XML, JSON, HTML or even a PDF. In addition, maybe I want version 1 of that resource as JSON. This can all be done using the Accept and Version headers of an HTTP request.

(There some arguments for including the version number in your hypermedia type as well. I have not fully subscribed to that approach, but it does make some sense.)

For those of you who have not fully subscribed to RESTful APIs and HATEOAS, I highly recommend taking the time to read through the sites linked below and consider unlearning the older ways of implementing APIs and consider learning why adhering to HATEOAS is important and beneficial.

And honestly, if you didn't believe in separation of concerns, why do you adhere to MVC?

Path to enlightenment

HATEOAS 101 - Brian Mulloy put together a great video presentation of what is HATEOAS
Why build hypermedia APIs - Great review of the why and how of hypermedia in respect to Rails.
Haters gonna HATEOAS - Steve Klabnik explaining the HATEOAS
REST APIs must be hypertext-driven - Fielding himself highlighting what makes up a REST API

For those working in Ruby

Grape - Gem, DSL for describing your API
Roar - Gem, presentation DSL for your resources
Swagger - Document your API
Postman - Chrome extension for testing your API


  1. Replies
    1. IEEE Final Year Project centers make amazing deep learning final year projects ideas for final year students Final Year Projects for CSE to training and develop their deep learning experience and talents.

      IEEE Final Year projects Project Centers in India are consistently sought after. Final Year Students Projects take a shot at them to improve their aptitudes, while specialists like the enjoyment in interfering with innovation.

      corporate training in chennai corporate training in chennai

      corporate training companies in india corporate training companies in india

      corporate training companies in chennai corporate training companies in chennai

      I have read your blog its very attractive and impressive. I like it your blog. Digital Marketing Company in Chennai Project Centers in Chennai

  2. It’d be a good idea to start reading books of interest to you, Beckie. I’m not sure that investing in real estate will relieve you of your 7-3 job but maybe it’s time for a career and lifestyle change. Little changes here and there that will add up to one big home

  3. Thank you for your post, I look for such article along time, today i find it finally. this post give me lots of advise it is very useful for me.paint by numbers custom

  4. Use Buffer to manage your social media so that you have more time for your business. Join 160000+ small businesses today. FB Hack Link

  5. Download Here. Kon-Boot crack may be a programme for Window frames versions of windows that on the QT escapes the verification system. Website

  6. Preach powerful messages on Birth of Christ celebrating Togetherness this Christmas Season. The message of Christmas is more than the Nativity, its God's plan and purpose for us. Christmas Wishes