REST API versioning

Options for versioning the API can be used when changes to API functions impact existing client access.

Changes to the API may affect functionality clients already depend on. For example, a change to the format of the response data or type (changing an integer to a float), will impact existing users. The options for managing this change will require versioning the API so that clients are not disrupted.

A new version of an API can be implemented by versioning either the resource URI, or specifying the version in a custom header. There are advantages and disadvantage in using either method and the choice depends on your preference.

URI Versioning

Putting the version in the URI is the recommended approach.

For example, a resource at:

http://host:port/gas/ws/r/group/xcf/resource

Is now at:

http://host:port/gas/ws/r/group/xcf/version/resource/

Even though this in principle breaks the constraint that the URI should refer to a unique resource, it is the preferred way. In effect it means that you have two versions of the API and are able to generate a different openapi.json specification per version based on the path of your REST API.

Versioning using a custom header

Alternatively, the version can be included in a custom header.

api-version:v2.0

The version must be specified by the client. Clients need to know which headers to specify before requesting a resource.

The API function retrieves the value of the header. If the version matches one specified, then that is the method that will be invoked. Based on this, the API can decide if it is capable of fulfilling the request and respond to the client appropriately.

Version syntax

The version specified need not be numeric, nor specified using the “v[x]” syntax. Alternatives such as dates, project names, or other identifiers that you find meaningful and flexible enough to change as the versions change can be used.