diff --git a/docs/specs/blueprint.rst b/docs/specs/blueprint.rst --- a/docs/specs/blueprint.rst +++ b/docs/specs/blueprint.rst @@ -1,31 +1,97 @@ Use cases --------- +The general idea is that a deposit can be created either in a single request +or by multiple requests to allow the user to add elements to the deposit piece +by piece (be it the deposited data or the metadata describing it). + +An update request that does not have the `In-Progress: true` HTTP header will +de facto declare the deposit as *completed* (aka in the `deposited` status; see +below) and thus ready for ingestion. + +Once the deposit is declared *complete* by the user, the server performs a few +validation checks. Then, if valid, schedule the ingestion of the deposited data +in the Software Heritage Archive (SWH). + +There is a `status` property attached to a deposit allowing to follow the +processing workflow of the deposit. For example, when this ingestion task +completes successfully, the deposit is marked as `done`. + + +Possible deposit statuses are: + +partial + The deposit is partially received, since it can be done in + multiple requests. + +expired + Deposit was there too long and is new deemed ready to be + garbage-collected. + +deposited + Deposit is complete, ready to be checked. + +rejected + Deposit failed the checks. + +verified + Deposit passed the checks and is ready for loading. + +loading + Injection is ongoing on SWH's side. + +done + Loading is successful. + +failed + Loading failed. + + +This document describes the possible scenarios for creating or updating a +deposit. + Deposit creation ~~~~~~~~~~~~~~~~ From client's deposit repository server to SWH's repository server: -1. The client requests for the server's abilities and its associated collection - (GET query to the *SD/service document uri*) +1. The client requests for the server's abilities and its associated + :ref:`collections ` using the *SD/service document uri* + (:http:get:`/1/servicedocument/`). -2. The server answers the client with the service document which gives the - *collection uri* (also known as *COL/collection IRI*). +2. The server answers the client with the service document which lists the + *collections* linked to the user account (most of the time, there will one and + only one collection linked to the user's account). Each of these collection can + be used to push a deposit via its *COL/collection IRI*. -3. The client sends a deposit (optionally a zip archive, some metadata or both) - through the *collection uri*. +3. The client sends a deposit (a zip archive, some metadata or both) through + the *COL/collection uri*. - This can be done in: + This can be done in: - * one POST request (metadata + archive). - * one POST request (metadata or archive) + other PUT or POST request to the - *update uris* (*edit-media iri* or *edit iri*) + * one POST request (metadata + archive) without the `In-Progress: true` header: - a. Server validates the client's input or returns detailed error if any + - :http:post:`/1/(str:collection-name)/` - b. Server stores information received (metadata or software archive source - code or both) + * one POST request (metadata or archive) **with** `In-Progress: true` header: + + - :http:post:`/1/(str:collection-name)/` + + plus one or more PUT or POST requests *to the update uris* + (*edit-media iri* or *edit iri*): + + - :http:post:`/1/(str:collection-name)/(int:deposit-id)/media/` + - :http:put:`/1/(str:collection-name)/(int:deposit-id)/media/` + - :http:post:`/1/(str:collection-name)/(int:deposit-id)/metadata/` + - :http:put:`/1/(str:collection-name)/(int:deposit-id)/metadata/` + + Then: + + a. Server validates the client's input or returns detailed error if any. + + b. Server stores information received (metadata or software archive source + code or both). 4. The server notifies the client it acknowledged the client's request. An ``http 201 Created`` response with a deposit receipt in the body response is @@ -36,42 +102,12 @@ Schema representation ^^^^^^^^^^^^^^^^^^^^^ -Scenario: pushing a deposit via SWORD protocol (nominal scenario) +Scenario: pushing a deposit via the SWORDv2_ protocol (nominal scenario): .. figure:: ../images/deposit-create-chart.svg :alt: -Deposit statuses: - -'partial' - The deposit is new or partially received, since it can be done in - multiple requests - -'expired' - Deposit was there too long and is new deemed ready to be - garbage-collected - -'deposited' - Deposit passed the checks - -'rejected' - Deposit failed the checks - -'verified' - Deposit passed the checks and is ready for loading - -'loading' - Injection is ongoing on SWH's side - -'done' - Loading is successful - -'failed' - Loading failed - - - Updating an existing deposit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -96,43 +132,16 @@ In this state, ``In-Progress`` is not allowed, so the deposit cannot go back in the ``partial`` state, but only to ``deposited``. + Schema representation ^^^^^^^^^^^^^^^^^^^^^ -Scenario: updating a deposit via SWORD protocol +Scenario: updating a deposit via SWORDv2_ protocol: .. figure:: ../images/deposit-update-chart.svg :alt: -Deposit statuses: - -'partial' - The deposit is new or partially received, since it can be done in - multiple requests - -'expired' - Deposit was there too long and is new deemed ready to be - garbage-collected - -'deposited' - Deposit passed the checks - -'rejected' - Deposit failed the checks - -'verified' - Deposit passed the checks and is ready for loading - -'loading' - Injection is ongoing on SWH's side - -'done' - Loading is successful - -'failed' - Loading failed - Deleting deposit (or associated archive, or associated metadata) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -142,48 +151,22 @@ 1. Server validates the client's input or returns detailed error if any 2. Server actually delete information according to request + Schema representation ^^^^^^^^^^^^^^^^^^^^^ -Scenario: deleting a deposit via SWORD protocol +Scenario: deleting a deposit via SWORDv2_ protocol: .. figure:: ../images/deposit-delete-chart.svg :alt: -Deposit statuses: - -'partial' - The deposit is new or partially received, since it can be done in - multiple requests - -'expired' - Deposit was there too long and is new deemed ready to be - garbage-collected - -'deposited' - Deposit passed the checks - -'rejected' - Deposit failed the checks - -'verified' - Deposit passed the checks and is ready for loading - -'loading' - Injection is ongoing on SWH's side - -'done' - Loading is successful - -'failed' - Loading failed - Client asks for operation status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 7. Operation status can be read through a GET query to the *state iri*. + Server: Triggering deposit checks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -192,6 +175,7 @@ fail, the status is changed to ``rejected`` and nothing more happens there. Otherwise, the status is changed to ``verified``. + Server: Triggering deposit load ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -201,4 +185,6 @@ The loading will result on status update, either ``done`` or ``failed`` (depending on the loading's status). -This is described in the `loading document <./spec-loading.html>`__. +This is described in the :ref:`loading specifications document `. + +.. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html