ceph/doc/mgr/ceph_api/index.rst

   1 .. _mgr ceph api:
   2
   3 ================
   4 Ceph RESTful API
   5 ================
   6
   7 Introduction
   8 ============
   9 The **Ceph RESTful API** (henceforth **Ceph API**) is provided by the
  10 :ref:`mgr-dashboard` module. The Ceph API
  11 service is available at the same URL as the regular Ceph Dashboard, under the
  12 ``/api`` base path (please refer to :ref:`dashboard-host-name-and-port`)::
  13
  14   http://<server_addr>:<server_port>/api
  15
  16 or, if HTTPS is enabled (please refer to :ref:`dashboard-ssl-tls-support`)::
  17
  18   https://<server_addr>:<ssl_server_port>/api
  19
  20 The Ceph API leverages the following standards:
  21
  22 * `HTTP 1.1 <https://tools.ietf.org/html/rfc7231>`_ for API syntax and semantics,
  23 * `JSON <https://tools.ietf.org/html/rfc8259>`_ for content encoding,
  24 * `HTTP Content Negotiation <https://tools.ietf.org/html/rfc2295>`_ and `MIME <https://tools.ietf.org/html/rfc2045>`_ for versioning,
  25 * `OAuth 2.0 <https://tools.ietf.org/html/rfc6750>`_ and `JWT <https://tools.ietf.org/html/rfc7519>`_ for authentication and authorization.
  26
  27 .. warning::
  28   Some endpoints are still under active development, and should be carefully
  29   used since new Ceph releases could bring backward incompatible changes.
  30
  31
  32 Authentication and Authorization
  33 ================================
  34
  35 Requests to the Ceph API pass through two access control checkpoints:
  36
  37 * **Authentication**: ensures that the request is performed on behalf of an existing and valid user account.
  38 * **Authorization**: ensures that the previously authenticated user can in fact perform a specific action (create, read, update or delete) on the target endpoint.
  39
  40 So, prior to start consuming the Ceph API, a valid JSON Web Token (JWT) has to
  41 be obtained, and it may then be reused for subsequent requests. The
  42 ``/api/auth`` endpoint will provide the valid token:
  43
  44 .. prompt:: bash $
  45
  46    curl -X POST "https://example.com:8443/api/auth" \
  47    -H  "Accept: application/vnd.ceph.api.v1.0+json" \
  48    -H  "Content-Type: application/json" \
  49    -d '{"username": <username>, "password": <password>}'
  50
  51 ::
  52
  53     { "token": "<redacted_token>", ...}
  54
  55 The token obtained must be passed together with every API request in the
  56 ``Authorization`` HTTP header::
  57
  58   curl -H "Authorization: Bearer <token>" ...
  59
  60 Authentication and authorization can be further configured from the
  61 Ceph CLI, the Ceph-Dashboard UI and the Ceph API itself (please refer to
  62 :ref:`dashboard-user-role-management`).
  63
  64 Versioning
  65 ==========
  66
  67 One of the main goals of the Ceph API is to keep a stable interface. For this
  68 purpose, Ceph API is built upon the following principles:
  69
  70 * **Mandatory**: in order to avoid implicit defaults, all endpoints require an explicit default version (starting with ``1.0``).
  71 * **Per-endpoint**: as this API wraps many different Ceph components, this allows for a finer-grained change control.
  72    * **Content/MIME Type**: the version expected from a specific endpoint is stated by the ``Accept: application/vnd.ceph.api.v<major>.<minor>+json`` HTTP header. If the current Ceph API server is not able to address that specific major version, a `415 - Unsupported Media Type <https://tools.ietf.org/html/rfc7231#section-6.5.13>`_ response will be returned.
  73 * **Semantic Versioning**: with a ``major.minor`` version:
  74    * Major changes are backward incompatible: they might result in non-additive changes to the request and/or response formats of a specific endpoint.
  75    * Minor changes are backward/forward compatible: they basically consists of additive changes to the request or response formats of a specific endpoint.
  76
  77 An example:
  78
  79 .. prompt:: bash $
  80
  81    curl -X GET "https://example.com:8443/api/osd" \
  82    -H  "Accept: application/vnd.ceph.api.v1.0+json" \
  83    -H  "Authorization: Bearer <token>"
  84
  85
  86 Specification
  87 =============
  88
  89 .. openapi:: ../../../src/pybind/mgr/dashboard/openapi.yaml
  90     :group:
  91     :examples:
  92     :encoding: utf-8