Should an API ever have version numbers in it?

Question

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.

Answer 1

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.

Answer 2

That could be reasonable if you're building an object oriented API and you give the version number to a factory. It's common in dynamic data centric APIs as well - you ask the library for data and have to indicate what format/version you want the data back as.

More commonly for "traditional" libraries(as in the ones you link to in your C/C++/.NET applications) done is:

• provide an API to fetch the version number of the library. This allows the application to decide if it needs a newer/older version of the library.

• be backwards compatible as long as you can.

• Add functions, don't change them. If you have to add arguments/input or change behavior - create a new function rather, and keep the old one around.

• when you eventually have to break backwards compatibility and get rid of all the old cruft kept around only for the sake of being backwards compatible, have a sane version scheme that clearly indicates incompatible versions.