Versioning for the Ceph API

The main goal for the Ceph RESTful API is to provide a stable interface, which is done by versioning.

To achieve a stable interface, the Ceph API is built on the following principles:
  • A mandatory explicit default version for all endpoints to avoid implicit defaults.

  • Fine-grain change control per-endpoint.

    • The expected version from a specific endpoint is stated in the HTTP header.

      Syntax

      Accept: application/vnd.ceph.api.vMAJOR.MINOR+json

      Example

      Accept: application/vnd.ceph.api.v1.0+json

      If the current Ceph API server is not able to address that specific version, a 415 - Unsupported Media Type response will be returned.

  • Using semantic versioning.

    • Major changes are backwards incompatible. Changes might result in non-additive changes to the request, and to the response formats for a specific endpoint.

    • Minor changes are backwards and forwards compatible. Changes consist of additive changes to the request or response formats for a specific endpoint.