API Versioning

Current Version: 1.0

General

The API will provide versioned API calls when a breaking change is made to an API call. That is, a change that causes any client calls to now fail, where they were previously working. Usually changes such as non mandatory field additions are deemed non breaking since the client can continue to use the fields and data for which they were designed and ignore the new fields/data.

It is for this reason, that we recommend that all API calls specify a version identifier which was defined at the time of the client development. this ensures that if any breaking changes are made, and the call is versioned, then the client will continue to work as expected as they will only access the older version of the api endpoint. specifying a version number for an api call that has no older versions has no effect, and the latest version of the api endpoint will be returned.

In general, all changes to API calls will have every attempt to retain backward compatibility and not introduce breaking changes. That is, when changes are made, consumers that are used to accessing the prior versions will continue to work. Usually this means we simply add information without breaking any structure or required fields/data.

However, in the circumstance where a breaking change is introduced, we will provide access to the prior version(s) of the changed API calls. Any versioning changes will be communicated and highlighted in the documentation along with the supported versions. Old versions of API calls will be marked as deprecated, and at most, 2 prior versions of an API call will be supported.

How to request a specific version

In order to request a specific version, the consumer must add a version specific header to the request. This is the "X-Api-Version" header.

The value of this header must be in the format: "MAJOR#.MINOR#" where "MAJOR#" represents the major version and "MINOR#" represents the minor version.

For example, if version 0.9 is required of a particular API method, then the header value must look like this: 

X-Api-Version: 0.9

Similarly, if version 1.0 of the API call is required, then the header value will look like: 

X-Api-Version: 1.0

A more complete view of the headers of an API request for a specific version (in this case 0.9) may look something like this: 

                         GET /invoices HTTP/1.1
                         Host: api.saasu.com
                         Content-Type: application/json
                         X-Api-Version: 0.9