Page Menu
Home
Software Heritage
Search
Configure Global Search
Log In
Files
F7066401
D4427.id.diff
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Flag For Later
Size
20 KB
Subscribers
None
D4427.id.diff
View Options
diff --git a/docs/endpoints/collection.rst b/docs/endpoints/collection.rst
--- a/docs/endpoints/collection.rst
+++ b/docs/endpoints/collection.rst
@@ -2,9 +2,9 @@
Create deposit
^^^^^^^^^^^^^^^
-.. http:post:: /1/<collection-name>/
+.. http:post:: /1/(str:collection-name)/
- Create deposit in a collection.
+ Create deposit in a collection which name is `collection-name`.
The client sends a deposit request to a specific collection with:
@@ -14,61 +14,69 @@
Also known as: COL-IRI
- :param text <name><pass>: the client's credentials
- :param text Content-Type: accepted mimetype
- :param int Content-Length: tarball size
- :param text Content-MD5: md5 checksum hex encoded of the tarball
- :param text Content-Disposition: attachment; filename=[filename]; the filename
- parameter must be text (ascii)
- :param text Content-Disposition: for the metadata file set name parameter
- to 'atom'.
- :param bool In-progress: true if not final; false when final request.
- :statuscode 201: success for deposit on POST
- :statuscode 401: Unauthorized
- :statuscode 404: access to an unknown collection
- :statuscode 415: unsupported media type
+ **Example query**:
-Sample request
-~~~~~~~~~~~~~~~
-.. code:: shell
+ .. code:: shell
- curl -i -u hal:<pass> \
- -F "file=@../deposit.json;type=application/zip;filename=payload" \
- -F "atom=@../atom-entry.xml;type=application/atom+xml;charset=UTF-8" \
+ curl -i -u hal:<pass> \
+ -F "file=@deposit.json;type=application/zip;filename=payload" \
+ -F "atom=@atom-entry.xml;type=application/atom+xml;charset=UTF-8" \
-H 'In-Progress: false' \
-H 'Slug: some-external-id' \
-XPOST https://deposit.softwareheritage.org/1/hal/
-Sample response
-~~~~~~~~~~~~~~~
-
-.. code:: shell
-
- HTTP/1.0 201 Created
- Date: Tue, 26 Sep 2017 10:32:35 GMT
- Server: WSGIServer/0.2 CPython/3.5.3
- Vary: Accept, Cookie
- Allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
- Location: /1/hal/10/metadata/
- X-Frame-Options: SAMEORIGIN
- Content-Type: application/xml
-
- <entry xmlns="http://www.w3.org/2005/Atom"
- xmlns:sword="http://purl.org/net/sword/"
- xmlns:dcterms="http://purl.org/dc/terms/">
- <deposit_id>10</deposit_id>
- <deposit_date>Sept. 26, 2017, 10:32 a.m.</deposit_date>
- <deposit_archive>None</deposit_archive>
- <deposit_status>deposited</deposit_status>
-
- <!-- Edit-IRI -->
- <link rel="edit" href="/1/hal/10/metadata/" />
- <!-- EM-IRI -->
- <link rel="edit-media" href="/1/hal/10/media/"/>
- <!-- SE-IRI -->
- <link rel="http://purl.org/net/sword/terms/add" href="/1/hal/10/metadata/" />
- <!-- State-IRI -->
- <link rel="alternate" href="/1/<collection-name>/10/status/"/>
-
- <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
- </entry>
+ .. code:: http
+
+ POST /1/hal/ HTTP/1.1
+ Host: deposit.softwareheritage.org
+ Authorization: Basic xxxxxxxxxxxx=
+ Slug: some-external-id
+ In-Progress: false
+ Content-Length: 123456
+ Content-Type: multipart/form-data; boundary=----------------------123456798
+
+ **Example response**:
+
+ .. code:: http
+
+ HTTP/1.1 201 Created
+ Date: Tue, 26 Sep 2017 10:32:35 GMT
+ Server: WSGIServer/0.2 CPython/3.5.3
+ Vary: Accept, Cookie
+ Allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
+ Location: /1/hal/10/metadata/
+ X-Frame-Options: SAMEORIGIN
+ Content-Type: application/xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/">
+ <deposit_id>10</deposit_id>
+ <deposit_date>Sept. 26, 2017, 10:32 a.m.</deposit_date>
+ <deposit_archive>None</deposit_archive>
+ <deposit_status>deposited</deposit_status>
+
+ <!-- Edit-IRI -->
+ <link rel="edit" href="/1/hal/10/metadata/" />
+ <!-- EM-IRI -->
+ <link rel="edit-media" href="/1/hal/10/media/"/>
+ <!-- SE-IRI -->
+ <link rel="http://purl.org/net/sword/terms/add" href="/1/hal/10/metadata/" />
+ <!-- State-IRI -->
+ <link rel="alternate" href="/1/hal/10/status/"/>
+
+ <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
+ </entry>
+
+ :reqheader Authorization: Basic authentication token
+ :reqheader Content-Type: accepted mimetype
+ :reqheader Content-Length: tarball size
+ :reqheader Content-MD5: md5 checksum hex encoded of the tarball
+ :reqheader Content-Disposition: attachment; filename=[filename]; the filename
+ parameter must be text (ascii); for the metadata file set name parameter
+ to 'atom'.
+ :reqheader In-progress: `true` if not final; `false` when final request.
+ :statuscode 201: success for deposit on POST
+ :statuscode 401: Unauthorized
+ :statuscode 404: access to an unknown collection
+ :statuscode 415: unsupported media type
diff --git a/docs/endpoints/content.rst b/docs/endpoints/content.rst
--- a/docs/endpoints/content.rst
+++ b/docs/endpoints/content.rst
@@ -1,7 +1,7 @@
Display content
^^^^^^^^^^^^^^^^
-.. http:get:: /1/<collection-name>/<deposit-id>/content/
+.. http:get:: /1/(str:collection-name)/(int:deposit-id)/content/
Display information on the content's representation in the sword
server.
@@ -9,6 +9,67 @@
Also known as: CONT-FILE-IRI
- :param text <name><pass>: the client's credentials
+ **Example query**:
+
+ .. code:: http
+
+ GET /deposit/1/test/1/content/ HTTP/1.1
+ Accept: */*
+ Accept-Encoding: gzip, deflate
+ Authorization: Basic xxxxxxxxxx
+ Connection: keep-alive
+ Host: deposit.softwareheritage.org
+
+ **Example response**:
+
+ .. code:: http
+
+ HTTP/1.1 200 OK
+ Allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
+ Connection: keep-alive
+ Content-Length: 1760
+ Content-Type: application/xml
+ Date: Thu, 05 Nov 2020 14:31:50 GMT
+ Server: nginx/1.19.2
+ Vary: Accept
+ X-Frame-Options: SAMEORIGIN
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/">
+ <deposit_id>1</deposit_id>
+ <deposit_status>done</deposit_status>
+ <deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</deposit_status_detail>
+
+ <sword:request>
+
+ <deposit_date>Oct. 28, 2020, 3:58 p.m.</deposit_date>
+ </sword:request>
+ <sword:request>
+
+ <metadata>
+ <id>test-01243065</id>
+ <title>Verifiable online voting system</title>
+ <author>{'name': 'Belenios', 'email': 'belenios@example.com'}</author>
+ <client>test</client>
+ <codemeta:url>https://gitlab.inria.fr/belenios/belenios</codemeta:url>
+ <codemeta:author>{'codemeta:name': 'Belenios Test User'}</codemeta:author>
+ <codemeta:license>{'codemeta:name': 'GNU Affero General Public License'}</codemeta:license>
+ <codemeta:version>1.12</codemeta:version>
+ <codemeta:keywords>Online voting</codemeta:keywords>
+ <external_identifier>test-01243065</external_identifier>
+ <codemeta:description>Verifiable online voting system</codemeta:description>
+ <codemeta:runtimePlatform>opam</codemeta:runtimePlatform>
+ <codemeta:developmentStatus>stable</codemeta:developmentStatus>
+ <codemeta:applicationCategory>test</codemeta:applicationCategory>
+ <codemeta:programmingLanguage>ocaml</codemeta:programmingLanguage>
+ </metadata>
+
+ <deposit_date>Oct. 28, 2020, 3:58 p.m.</deposit_date>
+ </sword:request>
+ </entry>
+
+
+ :reqheader Authorization: Basic authentication token
:statuscode 200: no error
:statuscode 401: Unauthorized
diff --git a/docs/endpoints/service-document.rst b/docs/endpoints/service-document.rst
--- a/docs/endpoints/service-document.rst
+++ b/docs/endpoints/service-document.rst
@@ -11,38 +11,54 @@
Also known as: SD-IRI - The Service Document IRI
- :param text <name><pass>: the client's credentials
- :statuscode 200: no error
- :statuscode 401: Unauthorized
+ **Example query**:
+
+ .. code:: http
+
+ GET /1/servicedocument/ HTTP/1.1
+ Host: deposit.softwareheritage.org
+ Authorization: Basic xxxxxxxxxxxx=
+
+ **Example response**:
+ .. code:: http
+ HTTP/1.1 200 OK
+ Allow: GET, POST, PUT, DELETE, HEAD, OPTIONS
+ Connection: keep-alive
+ Content-Length: 1247
+ Content-Type: application/xml
+ Date: Thu, 05 Nov 2020 14:27:05 GMT
+ Server: nginx/1.19.2
+ Vary: Accept
+ X-Frame-Options: SAMEORIGIN
-Sample response
-~~~~~~~~~~~~~~~
- .. code:: xml
-
- <?xml version="1.0" ?>
- <service xmlns:dcterms="http://purl.org/dc/terms/"
- xmlns:sword="http://purl.org/net/sword/terms/"
- xmlns:atom="http://www.w3.org/2005/Atom"
- xmlns="http://www.w3.org/2007/app">
-
- <sword:version>2.0</sword:version>
- <sword:maxUploadSize>20971520</sword:maxUploadSize>
-
- <workspace>
- <atom:title>The Software Heritage (SWH) archive</atom:title>
- <collection href="https://deposit.softwareherigage.org/1/hal/">
- <atom:title>SWH Software Archive</atom:title>
- <accept>application/zip</accept>
- <accept>application/x-tar</accept>
- <sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
- <dcterms:abstract>Software Heritage Archive</dcterms:abstract>
- <sword:mediation>false</sword:mediation>
- <sword:metadataRelevantHeader>false</sword:metadataRelevantHeader>
- <sword:treatment>Collect, Preserve, Share</sword:treatment>
- <sword:acceptPackaging>http://purl.org/net/sword/package/SimpleZip</sword:acceptPackaging>
- <sword:service>https://deposit.softwareheritage.org/1/hal/</sword:service>
- </collection>
- </workspace>
- </service>
+ <?xml version="1.0" ?>
+ <service xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:sword="http://purl.org/net/sword/terms/"
+ xmlns:atom="http://www.w3.org/2005/Atom"
+ xmlns="http://www.w3.org/2007/app">
+
+ <sword:version>2.0</sword:version>
+ <sword:maxUploadSize>20971520</sword:maxUploadSize>
+
+ <workspace>
+ <atom:title>The Software Heritage (SWH) archive</atom:title>
+ <collection href="https://deposit.softwareherigage.org/1/hal/">
+ <atom:title>SWH Software Archive</atom:title>
+ <accept>application/zip</accept>
+ <accept>application/x-tar</accept>
+ <sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
+ <dcterms:abstract>Software Heritage Archive</dcterms:abstract>
+ <sword:mediation>false</sword:mediation>
+ <sword:metadataRelevantHeader>false</sword:metadataRelevantHeader>
+ <sword:treatment>Collect, Preserve, Share</sword:treatment>
+ <sword:acceptPackaging>http://purl.org/net/sword/package/SimpleZip</sword:acceptPackaging>
+ <sword:service>https://deposit.softwareheritage.org/1/hal/</sword:service>
+ </collection>
+ </workspace>
+ </service>
+
+ :reqheader Authorization: Basic authentication token
+ :statuscode 200: no error
+ :statuscode 401: Unauthorized
diff --git a/docs/endpoints/status.rst b/docs/endpoints/status.rst
--- a/docs/endpoints/status.rst
+++ b/docs/endpoints/status.rst
@@ -1,7 +1,7 @@
Retrieve status
^^^^^^^^^^^^^^^^
-.. http:get:: /1/<collection-name>/<deposit-id>/
+.. http:get:: /1/(str:collection-name)/(int:deposit-id)/status/
Returns deposit's status.
@@ -17,37 +17,17 @@
Also known as STATE-IRI
- :param text <name><pass>: the client's credentials
- :statuscode 201: with the deposit's status
- :statuscode 401: Unauthorized
- :statuscode 404: access to an unknown deposit
-
-
-Rejected deposit
-~~~~~~~~~~~~~~~~
-
-It so happens that deposit could be rejected. In that case, the
-`deposit_status_detail` entry will explain failed checks.
-
-Many reasons are possibles, here are some:
-- Deposit without software archive (main goal of the deposit is to
- deposit software source code)
-
-- Deposit with malformed software archive (i.e archive within archive)
-
-- Deposit with invalid software archive (corrupted archive, although,
- this one should happen during upload and not during checks)
-
-- Deposit with unsupported archive format
+ **Example query**:
-- Deposit with missing metadata
+ .. code:: http
+ GET /1/hal/1/status/ HTTP/1.1
+ Host: deposit.softwareheritage.org
+ Authorization: Basic xxxxxxxxxxxx=
-Sample response
-~~~~~~~~~~~~~~~
- Successful deposit:
+ **Example successful deposit response**:
.. code:: xml
@@ -61,7 +41,7 @@
<deposit_swh_id_context>swh:1:dir:d83b7dda887dc790f7207608474650d4344b8df9;origin=https://forge.softwareheritage.org/source/jesuisgpl/;visit=swh:1:snp:68c0d26104d47e278dd6be07ed61fafb561d0d20;anchor=swh:1:rev:e76ea49c9ffbb7f73611087ba6e999b19e5d71eb;path=/</deposit_swh_id>
</entry>
- Rejected deposit:
+ **Example rejeced deposit response**:
.. code:: xml
@@ -72,3 +52,30 @@
<deposit_status>rejected</deposit_status>
<deposit_status_detail>- At least one url field must be compatible with the client's domain name (codemeta:url)</deposit_status_detail>
</entry>
+
+
+ :reqheader Authorization: Basic authentication token
+ :statuscode 201: with the deposit's status
+ :statuscode 401: Unauthorized
+ :statuscode 404: access to an unknown deposit
+
+
+Rejected deposit
+~~~~~~~~~~~~~~~~
+
+It so happens that deposit could be rejected. In that case, the
+`deposit_status_detail` entry will explain failed checks.
+
+Many reasons are possibles, here are some:
+
+- Deposit without software archive (main goal of the deposit is to
+ deposit software source code)
+
+- Deposit with malformed software archive (i.e archive within archive)
+
+- Deposit with invalid software archive (corrupted archive, although,
+ this one should happen during upload and not during checks)
+
+- Deposit with unsupported archive format
+
+- Deposit with missing metadata
diff --git a/docs/endpoints/update-media.rst b/docs/endpoints/update-media.rst
--- a/docs/endpoints/update-media.rst
+++ b/docs/endpoints/update-media.rst
@@ -1,12 +1,12 @@
Update content
^^^^^^^^^^^^^^^
-.. http:post:: /1/<collection-name>/<deposit-id>/media/
+.. http:post:: /1/(str:collection-name)/(int:deposit-id)/media/
Add archive(s) to a deposit. Only possible if the deposit's status
is partial.
-.. http:put:: /1/<collection-name>/<deposit-id>/media/
+.. http:put:: /1/(str:collection-name)/(int:deposit-id)/media/
Replace all content by submitting a new archive. Only possible if
the deposit's status is partial.
@@ -14,13 +14,13 @@
Also known as: *update iri* (EM-IRI)
- :param text <name><pass>: the client's credentials
- :param text Content-Type: accepted mimetype
- :param int Content-Length: tarball size
- :param text Content-MD5: md5 checksum hex encoded of the tarball
- :param text Content-Disposition: attachment; filename=[filename] ; the filename
+ :reqheader Authorization: Basic authentication token
+ :reqheader Content-Type: accepted mimetype
+ :reqheader Content-Length: tarball size
+ :reqheader Content-MD5: md5 checksum hex encoded of the tarball
+ :reqheader Content-Disposition: attachment; filename=[filename] ; the filename
parameter must be text (ascii)
- :param bool In-progress: true if not final; false when final request.
+ :reqheader In-progress: `true` if not final; `false` when final request.
:statuscode 204: success without payload on PUT
:statuscode 201: success for deposit on POST
:statuscode 401: Unauthorized
diff --git a/docs/endpoints/update-metadata.rst b/docs/endpoints/update-metadata.rst
--- a/docs/endpoints/update-metadata.rst
+++ b/docs/endpoints/update-metadata.rst
@@ -1,12 +1,12 @@
Update metadata
^^^^^^^^^^^^^^^^
-.. http:post:: /1/<collection-name>/<deposit-id>/metadata/
+.. http:post:: /1/(str:collection-name)/(int:deposit-id)/metadata/
Add metadata to a deposit. Only possible if the deposit's status
is partial.
-.. http:put:: /1/<collection-name>/<deposit-id>/metadata/
+.. http:put:: /1/(str:collection-name)/(int:deposit-id)/metadata/
Replace all metadata by submitting a new metadata file. Only possible if
the deposit's status is partial.
@@ -14,10 +14,10 @@
Also known as: *update iri* (SE-IRI)
- :param text <name><pass>: the client's credentials
- :param text Content-Disposition: attachment; filename=[filename] ; the filename
+ :reqheader Authorization: Basic authentication token
+ :reqheader Content-Disposition: attachment; filename=[filename] ; the filename
parameter must be text (ascii), with a name parameter set to 'atom'.
- :param bool In-progress: true if not final; false when final request.
+ :reqheader In-progress: `true` if not final; `false` when final request.
:statuscode 204: success without payload on PUT
:statuscode 201: success for deposit on POST
:statuscode 401: Unauthorized
diff --git a/docs/spec-api.rst b/docs/spec-api.rst
--- a/docs/spec-api.rst
+++ b/docs/spec-api.rst
@@ -25,6 +25,8 @@
compression algorithm gzip (.tar.gz, .tgz), bzip2 (.tar.bz2) , or lzma
(.tar.lzma)
+.. _swh-deposit-collection:
+
Collection
----------
@@ -72,31 +74,30 @@
* common errors:
- * 401 (unauthenticated) if a client does not provide credential or provide
+ * :http:statuscode:`401`:if a client does not provide credential or provide
wrong ones
- * 403 (forbidden) if a client tries access to a collection it does not own
- * 404 (not found) if a client tries access to an unknown collection
- * 404 (not found) if a client tries access to an unknown deposit
- * 415 (unsupported media type) if a wrong media type is provided to the
- endpoint
+ * :http:statuscode:`403` a client tries access to a collection it does not own
+ * :http:statuscode:`404` if a client tries access to an unknown collection
+ * :http:statuscode:`404` if a client tries access to an unknown deposit
+ * :http:statuscode:`415` if a wrong media type is provided to the endpoint
* archive/binary deposit:
- * 403 (forbidden) if the length of the archive exceeds the max size
+ * :http:statuscode:`403` the length of the archive exceeds the max size
configured
- * 412 (precondition failed) if the length or hash provided mismatch the
- reality of the archive.
- * 415 (unsupported media type) if a wrong media type is provided
+ * :http:statuscode:`412` the length or hash provided mismatch the reality of
+ the archive.
+ * :http:statuscode:`415` if a wrong media type is provided
* multipart deposit:
- * 412 (precondition failed) if the md5 hash provided mismatch the reality of
- the archive
- * 415 (unsupported media type) if a wrong media type is provided
+ * :http:statuscode:`412` the md5 hash provided mismatch the reality of the
+ archive
+ * :http:statuscode:`415` if a wrong media type is provided
* Atom entry deposit:
- * 400 (bad request) if the request's body is empty (for creation only)
+ * :http:statuscode:`400` if the request's body is empty (for creation only)
File Metadata
Details
Attached
Mime Type
text/plain
Expires
Nov 5 2024, 7:52 AM (8 w, 2 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3229182
Attached To
D4427: doc: improve the doc of API endpoints
Event Timeline
Log In to Comment