Tag Archives: REST

Please version a REST API

Martin Fowler says to use versioning as a last resort:

Some people, when confronted with a problem, think “I know, I’ll use versioning.” Now they have 2.1.0 problems.

The problem is that versioning can significantly complicate understanding, testing, and troubleshooting a system. As soon as you have multiple incompatible versions of the same service used by multiple consumers, developers have to maintain bug fixes in all supported versions. If they are maintained in a single codebase, developers risk breaking an old version by adding a new feature to a new version simply because of shared code pathways. If the versions are independently deployed, the operational footprint becomes more complex to monitor and support.

I don’t agree.  I’m a coding dinosaur who’s had to support commercial software releases on old 8″ floppies.  Maybe I am that naive RESTful architect he’s talking about but:

  • With versioning you don’t make modifications to all supported versions for a bug fix.  As he says don’t use a shared code pathway because that’s a bad source control model.  Treat the older code supporting that version as immutable.  Do document bugs in older versions so clients are aware of them.  Don’t modify the code for those versions.  You risk instability from cascading bugs caused by your bug fix.  Those versions are now cut in stone and don’t change.  Keep that code in place until that version of the API is no longer used (a problem for another post) then you can safely remove that version and the code behind it.
  • A bug fix is just another version.  Fixing a bug is installing a newer version of the software.  Some bugs need to be fixed but not in the older versions.  Even if a client is demanding you fix that version you must resist doing that.  Point them to the newer version with the bug fix.  A lot of bugs are benign, low priority or have workarounds so it’s best to just leave them in situ.  If you’re also a client for other micro services  behind your API then the operational footprint isn’t that complex.   If those services are also versioned then it’s just versioning all the way down.
  • With this you never have 2.1 problems using versioning.  Instead you’ll have many many smaller versions – 1, 2, 3, 4 ad infinitum.  They all could have different or the same bugs – some major, some minor.  Resist any pressure to create a 1.1 version when you’re already on version 5.  You replace instead of modify for a micro service (Martin Fowler footnotes this as Replaceable Component Architecture from Dan North).   I also saw this replacable micro service attitude at a recent presentation at the Boston Scala Meetup by Yoni Goldberg at Gilt.  For Gilt they could implement a later version safely in Scala instead of Java.  Let’s just keep the older versions around so we don’t break any clients using an older version.
  • With versioning you have a fail safe if a new version of the API has a serious problem that takes it down.  Just have the clients revert back to the older version and work on a newer version that does work.
  • With versioning your clients are calling an API version then it’s safe for you to install newer versions – this supports continuous deployment of software changes with lower risk.  You decouple any upgrade of the clients from an upgrade of the API.  The Client left hand doesn’t need to know what the API right hand is doing and can find out later.
  • You get to do smoke testing of the API after it’s in production and before clients are using it.  This assumes they call the API with a version.
  • Your clients get to decide when they use the new version.  A lot of customers don’t want to mess with upgrading their systems.  It’s a risk for them and they don’t care about the newer functionality or bug fixes.  They can just leave well enough alone and stick with the older version.

Version in a Web API

In Web API Design they say on page 13 to “Never release an API without a version and make the version mandatory.”  I don’t agree with this statement.

If I’m a developer I want the freedom to include or exclude a version from the URL.  Stick the version on the end and make it optional.  If I want to always get the latest and greatest from the API then I can leave off the version.  Maybe I’m just doing testing and always want the latest.  It’s possible the API may break but that should be up to me to decide.  Don’t force me to include the version by making it mandatory.

If someone is doing continuous deployment I could have many small changes in the API.  Usually the code supports both the old version and the new version of the API.  Even if I’m forced to include the version in the API the old API version can still break. Putting the version in the API will reduce the chances of breaking the API but it’s not completely avoidable.

A version number is really just an alias for a date/time stamp.  If I’m doing continuous deployment I won’t declare a version until I think enough changes have been released into the API to warrant it.  If you allow a date as well as a version in an API a client can use some intermediate slipstream version. So, using their account examples a versioned URL could be:

  • /account (always the current version)
  • /account/20140524015300 (ISO date format as repeated in RFC3339 but without the required date separator, T & Z)
  • /account/20140524 (simple ISO date)
  • /account/05242014 (USA date format of MMDDYYYY)
  • /account/V1 (with V1 as an alias to something 2014-05-24T00-00-00Z)
  • /account?v=1 (The facebook version as a query parameter is ok too)

It’s also possible to include an Accept-Datetime in the request header (why isn’t this date an ISO or RFC3339 format?).  If there are mutiple versions present I’d say the precedence is URL, query parameter, and header.

You could also include a version in the Accept content type. But you could have a mime type version independent of the resource version.  I’d be cautious about using a version in a mime type.

I’d accept any and all possible versions to make the API more robust.

Comments about versioning I referenced while writing this: