Page Menu
Home
Software Heritage
Search
Configure Global Search
Log In
Files
F7342989
D4429.id15685.diff
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Flag For Later
Size
7 KB
Subscribers
None
D4429.id15685.diff
View Options
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).
+
+Each 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 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.
+
+
+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 <swh-deposit-collection>` 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 <swh-loading-specs>`.
+
+.. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html
File Metadata
Details
Attached
Mime Type
text/plain
Expires
Mar 17 2025, 6:33 PM (7 w, 3 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3230574
Attached To
D4429: doc: add an introduction paragraph in blueprint.rst
Event Timeline
Log In to Comment