]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
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 | .. code-block:: sh | |
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 | { "token": "<redacted_token>", ...} | |
52 | ||
53 | The token obtained must be passed together with every API request in the | |
54 | ``Authorization`` HTTP header:: | |
55 | ||
56 | curl -H "Authorization: Bearer <token>" ... | |
57 | ||
58 | Authentication and authorization can be further configured from the | |
59 | Ceph CLI, the Ceph-Dashboard UI and the Ceph API itself (please refer to | |
60 | :ref:`dashboard-user-role-management`). | |
61 | ||
62 | Versioning | |
63 | ========== | |
64 | ||
65 | One of the main goals of the Ceph API is to keep a stable interface. For this | |
66 | purpose, Ceph API is built upon the following principles: | |
67 | ||
68 | * **Mandatory**: in order to avoid implicit defaults, all endpoints require an explicit default version (starting with ``1.0``). | |
69 | * **Per-endpoint**: as this API wraps many different Ceph components, this allows for a finer-grained change control. | |
70 | * **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. | |
71 | * **Semantic Versioning**: with a ``major.minor`` version: | |
72 | * Major changes are backward incompatible: they might result in non-additive changes to the request and/or response formats of a specific endpoint. | |
73 | * Minor changes are backward/forward compatible: they basically consists of additive changes to the request or response formats of a specific endpoint. | |
74 | ||
75 | An example: | |
76 | ||
77 | .. code-block:: bash | |
78 | ||
79 | $ curl -X GET "https://example.com:8443/api/osd" \ | |
80 | -H "Accept: application/vnd.ceph.api.v1.0+json" \ | |
81 | -H "Authorization: Bearer <token>" | |
82 | ||
83 | ||
84 | Specification | |
85 | ============= | |
86 | ||
87 | .. openapi:: ../../../src/pybind/mgr/dashboard/openapi.yaml | |
88 | :group: | |
89 | :examples: | |
90 | :encoding: utf-8 |