The first one is easy I think. If you add a new property to an entity there is no need to create a new version of the API as long as the property is not mandatory. Any decent JSON (or XML if you prefer that for your REST API) will just ignore things it doesn't understand. So a caller using the old version will just not care about the new property returned and when updating the entity it will not provide the added property which then defaults to something sensible. I would even go so far as to say that I recommend not making new properties mandatory even if you are tempted since multiple versions of the API might cause more frustration than just add another optional property. If however the new property is very important you want to add a new version to the API
The other variant I was thinking about is a little more interesting. Let's say that you have a property where you support only a few predefined values. For example: "red" and "green". What if you at some point want to add another allowed value like "yellow". Do you need a new version of the API? This does not feel as easy as the first one but I actually think it is. If you document your API saying that you might return anything and here are a few values that have documented meaning then I don't think you need to version your API. Especially since any client using an old version then would be expected to preserve any values it does not understand between a GET and PUT where an entity is updated. But with the added property we discussed first you can't easily do this since most parsers assume you know what you are looking for without preserving anything that is not understood.
All in all I tend to favor changes that don't require new versions of an API just to keep things simple. What do you do?
> The other variant I was thinking about is a little more interesting. Let's say that you have a property where you support only a few predefined values. For example: "red" and "green". What if you at some point want to add another allowed value like "yellow". Do you need a new version of the API?
ReplyDeleteNot really, unless you're generating code that has enums such as enum Color{Red,Green} etc. That's just undocumented behavior (just like bugs that you haven't discovered yet) and can exist without bumping the version.
However for the sake of documentation, you should not update API docs (except typo fixes etc) of an API version. API documents should also be snapshotted and should be made available for all versions you support.
If you're adding new parameters etc and you want to document those most definitely, then you can release a minor version, and take another snapshot of the docs (and do SDK code generation etc.) Also it's always beneficial to have a CHANGELOG of the API versions so that people would just take a look at the changelog items rather than diff'ing the API docs. :)