API Versioning

[phowells]

The section on API Lifecycle Management prescribes identifying a version number in the mime type of a requests ACCEPT header and references RFC4627 as an endorsement of this practice.

The RFC4627 does not at all endorse using the version component of a mime type to indicate an API version. It is specific to indicating the version of a JSON structure. It is possible for a single version of an API to support many different representations of the same resource.

A new version of an API can include changes other than the addition or deprecation of supported resource structures. Specific examples being new behavior in existing interfaces, new workflows, new endpoints, deprecated endpoints, new SLAs, etc... The API Guidelines should provide a versioning strategy that addresses API changes; the mime type versioning does not.

(We have an established API versioning strategy for the NRPP and BC Wildfire Rest APIs that uses a separate HTTP Header to indicate the desired version of the API.)

Also many of the frameworks that we use to build our REST services, including Jersey, Spring, and CFX do not support custom mine types out of the box and require considerable configuration to provide custom handlers to support the serialization of the custom types. The frameworks support application\json and application\xml out of the box with no additional effort.

As standard tools do not know what to do with the custom mime types it will also be more difficult for new clients to consume the APIs that use a mime type versioning strategy.

[jeff-card]

Thank you for your comment! A peer review was held on August 9th and we have the following feedback:

This issue was discussed at length and a suggestion was supported to use Semantic Versioning 2.0.0 as a guideline, summarized as:

o MAJOR version when you make incompatible API changes,

o MINOR version when you add functionality in a backwards compatible manner, and

o PATCH version when you make backwards compatible bug fixes.

An updated API versioning can be expected on the next iteration. Thanks!