A common question surrounding RESTful APIs is whether or not to version, with opinions split depending on the implementation. This was the topic covered in a recent article by John Vester for DZone’s Integration Zone.
A common approach is to ignore versioning when possible, such as when the API is serving an internal client. Similarly, if you control all of the clients that access the API you may not need to worry about versioning.
However, public-facing APIs, or where all clients are not under your direct control, can better serve the evolving needs of business by having some form of version control in place. As an example, changes in response data, such as moving the Status field into a collection of child objects, will revoke access to the Status field for certain users.
This kind of issue can be overcome by including the version in the URI, as used by Salesforce, Google and Twitter. Another common approach is to reference the version as a query parameter, as Netfilx and Ebay do. This makes it the caller’s prerogative to decide if or when to upgrade.
One argument against versioning holds that requesting a representation of a resource that is tied to a version also ties that representation to the resource ID. Another versioning concern relates to the updating of endpoints not changed in the new version, causing discrepancies between endpoint versions that should be consistent.
The decision to version or not comes down to developer choice and need, but Vester advises away from versioning your API unless absolutely required.