Tag Archives: Martin Fowler

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.