Versioning

The Tahatū Occupation API has versioning ensuring new changes introduce can be rolled out without breaking current systems. Once a new version is introduced only 3 versions back will be supported.

There is a route to retrieve the current API version. 

GET /info

Each route now has a version number that is tied to an overall current version number. The API version is applied per route. If a route has an update then the route number will be incremented and both versions will be temporarily supported. 

Generally, the number of supported API versions should be minimal. One current major version and the previous major version will be supported. For minor versions, the current version plus two previous versions will be supported. 

A major change is denoted as a definite breaking change that significantly changes the way the API or a route has changed that will require the consumers to make their own updates to accommodate this.  A minor change is denoted as any other change that consumers should be aware of, these also may have downstream impact. 

To request a specific version route, the version can optionally be supplied in two different ways. If it is not supplied, it will default to the current version. The version number is supplied either through the route URL or as a parameter in the headers. 

Either through the route: 

GET /v1.0/occupations

Or through parameters supplied as a header: 

x-api-version = 1.0 

The response header then contains the supported versions for that particular route and also the deprecated versions for that route. 

api-supported-versions = 1.0, 1.1

deprecated-versions = 0.9