REST API endpoint versioning

Overview

The REST API versioning method uses two dedicated request headers to independently communicate the generation version and the endpoint version.

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

• Removing an entire operation
• Removing or renaming a parameter
• Removing or renaming a response field
• Adding a new required parameter
• Making a previously optional parameter required
• Changing the type of a parameter or response field
• Removing enum values
• Adding a new validation rule to an existing parameter
• Changing authentication or authorization requirements

Any additive (nonbreaking) changes are available in all supported API versions. Additive changes are changes that should not break an integration. Additive changes include:

• Adding an operation
• Adding an optional parameter
• Adding an optional request header
• Adding a response field
• Adding a response header
• Adding enum values

Version headers

In R1.0, both version identifiers are provided in the request header. The following two headers must be included in each request:

X-API-Version

Specifies the generation version of the API.

The generation version is updated only when a significant product generation change occurs. A licensed code level update does not update this value.

At R1.0, the value 1 must be used.

X-API-Release

Specifies the endpoint version of the API.

The endpoint version is updated when the licensed code level is updated, and it applies to all endpoints at the same time. The REST API returns GET data corresponding with the specified endpoint version.

At R1.0, the value 1.0 must be used.

The following table summarizes the R1.0 header-based versioning:

Usage rules

The following usage rules apply to the R1.0 versioning method:

• Both X-API-Version and X-API-Release must be specified in the request header for every request.
• Whenever the licensed code is updated, the new endpoint version corresponding to the new code level becomes available to all existing and new endpoints automatically, regardless of any RESTful API content changes.
• When an endpoint is not supported at the specified release level, HTTP RC=404 (Not Found) is returned.
• If X-API-Release is not specified in the request header, a GET request returns the latest schema content supported at the target cluster.
• If an older content or schema is required, specify the X-API-Release value that corresponds to the earlier release level.

Example request

The following example shows a query to request the properties of the cartridge pool using the R1.0 versioning headers:

curl -k -s -v "https://<ip_address>/api/cartridgePools" \
  -H "X-API-Version: 1" \
  -H "X-API-Release: 1.0" \
  -H "Authorization: Bearer xxxxx"