Changeset View
Changeset View
Standalone View
Standalone View
docs/specs/blueprint.rst
| Use cases | Use cases | ||||
| --------- | ========= | ||||
| The general idea is that a deposit can be created either in a single request | 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 | 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). | 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 | 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 | de facto declare the deposit as *completed* (aka in the `deposited` status; see | ||||
| below) and thus ready for ingestion. | below) and thus ready for ingestion. | ||||
| Show All 36 Lines | failed | ||||
| Loading failed. | Loading failed. | ||||
| This document describes the possible scenarios for creating or updating a | This document describes the possible scenarios for creating or updating a | ||||
| deposit. | deposit. | ||||
| Deposit creation | Deposit creation | ||||
| ~~~~~~~~~~~~~~~~ | ---------------- | ||||
| From client's deposit repository server to SWH's repository server: | From client's deposit repository server to SWH's repository server: | ||||
| 1. The client requests for the server's abilities and its associated | 1. The client requests for the server's abilities and its associated | ||||
| :ref:`collections <swh-deposit-collection>` using the *SD/service document uri* | :ref:`collections <swh-deposit-collection>` using the *SD/service document uri* | ||||
| (:http:get:`/1/servicedocument/`). | (:http:get:`/1/servicedocument/`). | ||||
| 2. The server answers the client with the service document which lists the | 2. The server answers the client with the service document which lists the | ||||
| Show All 40 Lines | |||||
| Scenario: pushing a deposit via the SWORDv2_ protocol (nominal scenario): | Scenario: pushing a deposit via the SWORDv2_ protocol (nominal scenario): | ||||
| .. figure:: ../images/deposit-create-chart.svg | .. figure:: ../images/deposit-create-chart.svg | ||||
| :alt: | :alt: | ||||
| Updating an existing deposit | Updating an existing deposit | ||||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | """""""""""""""""""""""""""" | ||||
| 5. Client updates existing deposit through the *update uris* (one or more POST | 5. Client updates existing deposit through the *update uris* (one or more POST | ||||
| or PUT requests to either the *edit-media iri* or *edit iri*). | or PUT requests to either the *edit-media iri* or *edit iri*). | ||||
| 1. Server validates the client's input or returns detailed error if any | 1. Server validates the client's input or returns detailed error if any | ||||
| 2. Server stores information received (metadata or software archive source | 2. Server stores information received (metadata or software archive source | ||||
| code or both) | code or both) | ||||
| Show All 12 Lines | |||||
| In this state, ``In-Progress`` is not allowed, so the deposit cannot go back | In this state, ``In-Progress`` is not allowed, so the deposit cannot go back | ||||
| in the ``partial`` state, but only to ``deposited``. | in the ``partial`` state, but only to ``deposited``. | ||||
| As a failsafe, to avoid accidentally updating the wrong deposit, this requires | As a failsafe, to avoid accidentally updating the wrong deposit, this requires | ||||
| the ``X-Check-SWHID`` HTTP header to be set to the value of the SWHID of the | the ``X-Check-SWHID`` HTTP header to be set to the value of the SWHID of the | ||||
| deposit's content (returned after the deposit finished loading). | deposit's content (returned after the deposit finished loading). | ||||
| Schema representation | Schema representation | ||||
| ^^^^^^^^^^^^^^^^^^^^^ | """"""""""""""""""""" | ||||
| Scenario: updating a deposit via SWORDv2_ protocol: | Scenario: updating a deposit via SWORDv2_ protocol: | ||||
| .. figure:: ../images/deposit-update-chart.svg | .. figure:: ../images/deposit-update-chart.svg | ||||
| :alt: | :alt: | ||||
| Deleting deposit (or associated archive, or associated metadata) | Deleting deposit (or associated archive, or associated metadata) | ||||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" | ||||
| 6. Deposit deletion is possible as long as the deposit is still in ``partial`` | 6. Deposit deletion is possible as long as the deposit is still in ``partial`` | ||||
| state. | state. | ||||
| 1. Server validates the client's input or returns detailed error if any | 1. Server validates the client's input or returns detailed error if any | ||||
| 2. Server actually delete information according to request | 2. Server actually delete information according to request | ||||
| Schema representation | Schema representation | ||||
| ^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^ | ||||
| Scenario: deleting a deposit via SWORDv2_ protocol: | Scenario: deleting a deposit via SWORDv2_ protocol: | ||||
| .. figure:: ../images/deposit-delete-chart.svg | .. figure:: ../images/deposit-delete-chart.svg | ||||
| :alt: | :alt: | ||||
| Client asks for operation status | Client asks for operation status | ||||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | """""""""""""""""""""""""""""""" | ||||
| 7. Operation status can be read through a GET query to the *state iri*. | 7. Operation status can be read through a GET query to the *state iri*. | ||||
| Server: Triggering deposit checks | Server: Triggering deposit checks | ||||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | """"""""""""""""""""""""""""""""" | ||||
| Once the status ``deposited`` is reached for a deposit, checks for the | Once the status ``deposited`` is reached for a deposit, checks for the | ||||
| associated archive(s) and metadata will be triggered. If those checks | associated archive(s) and metadata will be triggered. If those checks | ||||
| fail, the status is changed to ``rejected`` and nothing more happens | fail, the status is changed to ``rejected`` and nothing more happens | ||||
| there. Otherwise, the status is changed to ``verified``. | there. Otherwise, the status is changed to ``verified``. | ||||
| Server: Triggering deposit load | Server: Triggering deposit load | ||||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | """"""""""""""""""""""""""""""" | ||||
| Once the status ``verified`` is reached for a deposit, loading the | Once the status ``verified`` is reached for a deposit, loading the | ||||
| deposit with its associated metadata will be triggered. | deposit with its associated metadata will be triggered. | ||||
| The loading will result on status update, either ``done`` or ``failed`` | The loading will result on status update, either ``done`` or ``failed`` | ||||
| (depending on the loading's status). | (depending on the loading's status). | ||||
| This is described in the :ref:`loading specifications document <swh-loading-specs>`. | This is described in the :ref:`loading specifications document <swh-loading-specs>`. | ||||
| .. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html | .. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html | ||||