Aug 24

The Interface to Yog-Sothoth

Subtitled: The ever-changing API and the Path to Madness

Agile Software Development is (at least partially) about the fact that change happens in software projects, and, as practitioners, it is clear that resisting change seems to be more expensive and error-inducing than simply accepting it.

But the fact that this is generally true certainly doesn’t make it always true. Consider the noble API.

Imagine, if you will, that someone, let’s call them Calidon Systems, produces an API that gives you access to their cool database of information about, say, movies. Your organization writes a bunch of applications using the API, and produces some excellent work.

And then Calidon Systems abruptly change the API, in substantial and semantically meaningful ways (like, for example, replacing a web-service/SOAP based API with a REST API).

Suddenly, you’re obliged to do a whole bunch of unanticipated work trying to repair your application to use the new API.

And then, a few months later, Calidon Systems announce that they have performance issues with the REST approach, and are switching to a Message-Queue style communications model.

I don’t know about you, but if I was a customer of this API, I would be pissed as hell. If I had do, I’d grimace and make the changes (again), but a voice at the back of my head would be whispering “Never use an API from Calidon Systems again

If your API is going to be used by more than a handful of people, you owe it to them, and to your reputation as a developer, to change it rarely, incrementally, and, as much as possible, in a backwards-compatible way.

If you’re building APIs for your internal development co-workers, this probably isn’t an issue, since you and they are both working towards the same overall goal. In that kind of environment, changing your API to deal with new features, etc, is probably a good thing. But that’s because the number of users and the people affected by the change is small.

If your API is public – if it is used by many programs, third-party developers, etc, it almost instantly becomes legacy code. Don’t refactor it every week. Don’t introduce changes to the interface calls, new objects, etc on a regular basis. Keep it extremely well documented. Do your very best to get it right the first time, and do your very best to maintain backwards compatibility for years.

Public is the key word in this whole post – once an API is public, you should consider it to be nigh-unchangeable. You do not have the luxury of fiddling with it, at least not with your reputation intact.

The best strategy I can suggest is to try a two-pass approach:

  • Beta: Do your level best to build an API that satisifies a number of known customers. Leaving the “Beta” tag attached, release it to a relatively small group of people, with the understanding that it will change based on their feedback.
  • Release: Once you get feedback, release a final version, and keep it as stable as you can for at least a year, preferably two or more.

This video on the subject was very helpful in reinforcing that my opinions here are not completely off base 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>