Changeset View
Changeset View
Standalone View
Standalone View
docs/api.rst
Show All 30 Lines | |||||
- directories | - directories | ||||
- revisions | - revisions | ||||
- snapshots | - snapshots | ||||
The URL fragment ``:objectkind/:objectid`` is used throughout the vault API to | The URL fragment ``:objectkind/:objectid`` is used throughout the vault API to | ||||
identify vault objects. The syntax and meaning of ``:objectid`` for the | identify vault objects. The syntax and meaning of ``:objectid`` for the | ||||
different object kinds is detailed below. | different object kinds is detailed below. | ||||
Optionally, a third parameter, ``:format``, can be used (when multiple formats | In the case of revisions, a third parameter, ``:format``, must be used to | ||||
are supported) to specify the format of the resulting bundle when needed. The | specify the format of the resulting bundle. The URL fragment becomes then | ||||
URL fragment becomes then ``:objectkind/:objectid/:format``. | ``:objectkind/:objectid/:format``. | ||||
Directories | Directories | ||||
~~~~~~~~~~~ | ~~~~~~~~~~~ | ||||
- object kind: ``directory`` | - object kind: ``directory`` | ||||
- URL fragment: ``directory/:dir_id`` | - URL fragment: ``directory/:dir_id`` | ||||
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines | |||||
--------------------------- | --------------------------- | ||||
Vault bundles might be ready for retrieval or not. When they are not, they will | Vault bundles might be ready for retrieval or not. When they are not, they will | ||||
need to be **cooked** before they can be retrieved. A cooked bundle will remain | need to be **cooked** before they can be retrieved. A cooked bundle will remain | ||||
around until it expires; after expiration, it will need to be cooked again | around until it expires; after expiration, it will need to be cooked again | ||||
before it can be retrieved. Cooking is idempotent, and a no-op in between a | before it can be retrieved. Cooking is idempotent, and a no-op in between a | ||||
previous cooking operation and expiration. | previous cooking operation and expiration. | ||||
.. http:post:: /vault/:objectkind/:objectid/:format | .. http:post:: /vault/:objectkind/:objectid[/:format] | ||||
.. http:get:: /vault/:objectkind/:objectid/:format | .. http:get:: /vault/:objectkind/:objectid[/:format] | ||||
**Request body**: optionally, an ``email`` POST parameter containing an | **Request body**: optionally, an ``email`` POST parameter containing an | ||||
e-mail to notify when the bundle cooking has ended. | e-mail to notify when the bundle cooking has ended. | ||||
**Allowed HTTP Methods:** | **Allowed HTTP Methods:** | ||||
- :http:method:`post` to **request** a bundle cooking | - :http:method:`post` to **request** a bundle cooking | ||||
- :http:method:`get` to check the progress and status of the cooking | - :http:method:`get` to check the progress and status of the cooking | ||||
▲ Show 20 Lines • Show All 45 Lines • ▼ Show 20 Lines | - ``status``: one of the following values: | ||||
- ``done``: the bundle has been cooked and is ready for retrieval | - ``done``: the bundle has been cooked and is ready for retrieval | ||||
- ``failed``: the bundle cooking failed and can be retried | - ``failed``: the bundle cooking failed and can be retried | ||||
Retrieval | Retrieval | ||||
--------- | --------- | ||||
Retrieve a specific bundle from the vault with: | Retrieve a specific bundle from the vault with: | ||||
.. http:get:: /vault/:objectkind/:objectid/:format/raw | .. http:get:: /vault/:objectkind/:objectid[/:format]/raw | ||||
Where ``:format`` is optional, depending on the object kind. | Where ``:format`` is optional, depending on the object kind. | ||||
**Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, | **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, | ||||
:http:method:`options` | :http:method:`options` | ||||
**Response**: | **Response**: | ||||
:statuscode 200: bundle available; response body is the bundle. | :statuscode 200: bundle available; response body is the bundle. | ||||
:statuscode 404: unavailable bundle; client should request its cooking. | :statuscode 404: unavailable bundle; client should request its cooking. |