In Web API Design they say on page 13 to “Never release an API without a version and make the version mandatory.” I don’t agree with this statement.
If I’m a developer I want the freedom to include or exclude a version from the URL. Stick the version on the end and make it optional. If I want to always get the latest and greatest from the API then I can leave off the version. Maybe I’m just doing testing and always want the latest. It’s possible the API may break but that should be up to me to decide. Don’t force me to include the version by making it mandatory.
If someone is doing continuous deployment I could have many small changes in the API. Usually the code supports both the old version and the new version of the API. Even if I’m forced to include the version in the API the old API version can still break. Putting the version in the API will reduce the chances of breaking the API but it’s not completely avoidable.
A version number is really just an alias for a date/time stamp. If I’m doing continuous deployment I won’t declare a version until I think enough changes have been released into the API to warrant it. If you allow a date as well as a version in an API a client can use some intermediate slipstream version. So, using their account examples a versioned URL could be:
- /account (always the current version)
- /account/20140524015300 (ISO date format as repeated in RFC3339 but without the required date separator, T & Z)
- /account/20140524 (simple ISO date)
- /account/05242014 (USA date format of MMDDYYYY)
- /account/V1 (with V1 as an alias to something 2014-05-24T00-00-00Z)
- /account?v=1 (The facebook version as a query parameter is ok too)
It’s also possible to include an Accept-Datetime in the request header (why isn’t this date an ISO or RFC3339 format?). If there are mutiple versions present I’d say the precedence is URL, query parameter, and header.
You could also include a version in the Accept content type. But you could have a mime type version independent of the resource version. I’d be cautious about using a version in a mime type.
I’d accept any and all possible versions to make the API more robust.
Comments about versioning I referenced while writing this: