api-design

Should an API ever have version numbers in it?


I am building an API which I intend to upgrade over time. Is it ever reasonable to include a version number as an argument in the API?

I'm writing a key/value store API in Ruby, Java, Erlang, and C#. I want to build something that is extensible as I know there are many things I have not thought of yet that may have to be incorporated in the future. However, I want to know if there is a clean way of doing this and whether version numbers play a part in this too.


Solution

  • You can do it, it's better (IMHO) if you just make your API backwards-compatible though. It's generally easier, as you don't need to branch on your side, based on the version number, you just re-implement the given method.

    I suppose it's really quite implementation-specific (and also environment-specific). I'd do whatever seems easiest/better.

    I'd say as long as your maintaining backwards compatibility in some fashion, then it's all good.