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.
Advertisements

2 responses

  1. I think your method has merit in commercial software situations. But, the majority of ReSTful api’s today are built to be open to the public. There can’t be new versions that frequently as there is no SLA forcing them to update to new versions as you tell them. Any bug fixes to the API that don’t introduce a breaking change should be done in version.

    Other than that, I do agree with your points – especially that “using versioning as a last resort” is a bad idea. Versioning should be thought of right away, and built into your release cycles. Anyone who isn’t thinking about this just hasn’t hit the situation where they release how important it is yet. But it’s only a matter of time.

  2. Angelo,

    if you’re using an optional version in the URI or header or mime type then any client who doesn’t include a version in the request uses the latest version. If they include a version they stay with that version until they update their request.

    I would never tell or force a client to update to the new version. But if they pull an OPTIONS or HEAD that could list the versions available and they can choose a version from that. I’m not sure how you’d provide the client with a description of what changed with each version.

    A bug fix to the API might not be a breaking change but any bug fix could inadvertently cause other bugs. Now you have a new heisenberg bug that is both in and not in the code depending on when you installed the bug fix. Suppose a client calls in with a problem on the API. When did that call get executed? Was is before or after you slipstreamed a bug fix into the API? Do you have the old code available for testing if the API was called before the bug fix? If you version the bug fix both the old version and new version are available for testing.

    I believe all software is commercial software and should be managed as such.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: