How NOT to Migrate your API

Let’s say you are a huge website with an application platform and API that other companies have invested many millions of dollars in.  You decide to improve that platform, great.  You decide to make it a major renovation rather than a series of improvements, not so great, but we’ll let that slide since the old one was so … quirky.  You set up the new version in a sandbox and let people migrate it gradually, great.  This new API makes unecessary changes to things like parameter names, not great at all.  You eventually decide that the new one is ready for prime time, great!  So you decide to replace the old API with the new API, and by replace you mean that the new one is where the old one used to be, complete with it’s renamed parameters and total lack of backwards compatibility, VERY MUCH NOT GREAT.

If you want to put out 2.0 of your API, you put it at a new place, and eventually shut off the old one if you need to.  You DO NOT pull a switcheroo without ensuring compatibility, just like you do not replace a 2nd floor window with a door unless you’ve had the foresight to put a floor on the other side.


  1. Ok, you need to name names. You’ve got my curiosity piqued. Who was it?

  2. […] like we’re being slapped around. Am I being harsh? I’m not making this stuff up and we’ve alluded to it before. Check out the developer forums and you’ll see what I […]