diff --git a/docs/endpoints/collection.rst b/docs/endpoints/collection.rst index 10326d76..0513fe5c 100644 --- a/docs/endpoints/collection.rst +++ b/docs/endpoints/collection.rst @@ -1,74 +1,82 @@ .. _API-create-deposit: Create deposit ^^^^^^^^^^^^^^^ -.. http:post:: /1// +.. 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: * an archive holding the software source code (binary upload) * an envelop with metadata describing information regarding a deposit (atom entry deposit) Also known as: COL-IRI - :param text : 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: \ - -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: \ + -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 - - - 10 - Sept. 26, 2017, 10:32 a.m. - None - deposited - - - - - - - - - - - http://purl.org/net/sword/package/SimpleZip - + .. 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 + + + 10 + Sept. 26, 2017, 10:32 a.m. + None + deposited + + + + + + + + + + + http://purl.org/net/sword/package/SimpleZip + + + :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 index ef89d1e9..686ee20a 100644 --- a/docs/endpoints/content.rst +++ b/docs/endpoints/content.rst @@ -1,14 +1,75 @@ Display content ^^^^^^^^^^^^^^^^ -.. http:get:: /1///content/ +.. http:get:: /1/(str:collection-name)/(int:deposit-id)/content/ Display information on the content's representation in the sword server. Also known as: CONT-FILE-IRI - :param text : 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 + + + 1 + done + The deposit has been successfully loaded into the Software Heritage archive + + + + Oct. 28, 2020, 3:58 p.m. + + + + + test-01243065 + Verifiable online voting system + {'name': 'Belenios', 'email': 'belenios@example.com'} + test + https://gitlab.inria.fr/belenios/belenios + {'codemeta:name': 'Belenios Test User'} + {'codemeta:name': 'GNU Affero General Public License'} + 1.12 + Online voting + test-01243065 + Verifiable online voting system + opam + stable + test + ocaml + + + Oct. 28, 2020, 3:58 p.m. + + + + + :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 index 97a7af19..924a4e20 100644 --- a/docs/endpoints/service-document.rst +++ b/docs/endpoints/service-document.rst @@ -1,48 +1,64 @@ Service document ^^^^^^^^^^^^^^^^^ .. http:get:: /1/servicedocument/ This is the starting endpoint for the client to discover its initial collection. The answer to this query will describes: * the server's abilities * connected client's collection information Also known as: SD-IRI - The Service Document IRI - :param text : 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 - - - - - 2.0 - 20971520 - - - The Software Heritage (SWH) archive - - SWH Software Archive - application/zip - application/x-tar - Collection Policy - Software Heritage Archive - false - false - Collect, Preserve, Share - http://purl.org/net/sword/package/SimpleZip - https://deposit.softwareheritage.org/1/hal/ - - - + + + + 2.0 + 20971520 + + + The Software Heritage (SWH) archive + + SWH Software Archive + application/zip + application/x-tar + Collection Policy + Software Heritage Archive + false + false + Collect, Preserve, Share + http://purl.org/net/sword/package/SimpleZip + https://deposit.softwareheritage.org/1/hal/ + + + + + :reqheader Authorization: Basic authentication token + :statuscode 200: no error + :statuscode 401: Unauthorized diff --git a/docs/endpoints/status.rst b/docs/endpoints/status.rst index ca773b0b..25ffa93b 100644 --- a/docs/endpoints/status.rst +++ b/docs/endpoints/status.rst @@ -1,74 +1,81 @@ Retrieve status ^^^^^^^^^^^^^^^^ -.. http:get:: /1/// +.. http:get:: /1/(str:collection-name)/(int:deposit-id)/status/ Returns deposit's status. The different statuses: - **partial**: multipart deposit is still ongoing - **deposited**: deposit completed, ready for checks - **rejected**: deposit failed the checks - **verified**: content and metadata verified, ready for loading - **loading**: loading in-progress - **done**: loading completed successfully - **failed**: the deposit loading has failed Also known as STATE-IRI - :param text : 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 160 done The deposit has been successfully loaded into the Software Heritage archive swh:1:dir:d83b7dda887dc790f7207608474650d4344b8df9 swh:1:dir:d83b7dda887dc790f7207608474650d4344b8df9;origin=https://forge.softwareheritage.org/source/jesuisgpl/;visit=swh:1:snp:68c0d26104d47e278dd6be07ed61fafb561d0d20;anchor=swh:1:rev:e76ea49c9ffbb7f73611087ba6e999b19e5d71eb;path=/ - Rejected deposit: + **Example rejeced deposit response**: .. code:: xml 148 rejected - At least one url field must be compatible with the client's domain name (codemeta:url) + + + :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 index de32634c..3b275576 100644 --- a/docs/endpoints/update-media.rst +++ b/docs/endpoints/update-media.rst @@ -1,27 +1,27 @@ Update content ^^^^^^^^^^^^^^^ -.. http:post:: /1///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///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. Also known as: *update iri* (EM-IRI) - :param text : 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 :statuscode 415: unsupported media type diff --git a/docs/endpoints/update-metadata.rst b/docs/endpoints/update-metadata.rst index 661d7516..446692eb 100644 --- a/docs/endpoints/update-metadata.rst +++ b/docs/endpoints/update-metadata.rst @@ -1,24 +1,24 @@ Update metadata ^^^^^^^^^^^^^^^^ -.. http:post:: /1///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///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. Also known as: *update iri* (SE-IRI) - :param text : 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 :statuscode 415: unsupported media type diff --git a/docs/spec-api.rst b/docs/spec-api.rst index 4a6b3cc2..d45acb95 100644 --- a/docs/spec-api.rst +++ b/docs/spec-api.rst @@ -1,112 +1,113 @@ API Specification ================= This is `Software Heritage `__'s `SWORD 2.0 `__ Server implementation. **S.W.O.R.D** (**S**\ imple **W**\ eb-Service **O**\ ffering **R**\ epository **D**\ eposit) is an interoperability standard for digital file deposit. This implementation will permit interaction between a client (a repository) and a server (SWH repository) to push deposits of software source code archives with associated metadata. *Note:* * In the following document, we will use the ``archive`` or ``software source code archive`` interchangeably. * The supported archive formats are: * zip: common zip archive (no multi-disk zip files). * tar: tar archive without compression or optionally any of the following compression algorithm gzip (.tar.gz, .tgz), bzip2 (.tar.bz2) , or lzma (.tar.lzma) +.. _swh-deposit-collection: + Collection ---------- SWORD defines a ``collection`` concept. In SWH's case, this collection refers to a group of deposits. A ``deposit`` is some form of software source code archive(s) associated with metadata. By default the client's collection will have the client's name. Limitations ----------- * upload limitation of 100Mib * no mediation API overview ------------ API access is over HTTPS. The API is protected through basic authentication. Endpoints --------- The API endpoints are rooted at https://deposit.softwareheritage.org/1/. Data is sent and received as XML (as specified in the SWORD 2.0 specification). .. include:: endpoints/service-document.rst .. include:: endpoints/collection.rst .. include:: endpoints/update-media.rst .. include:: endpoints/update-metadata.rst .. include:: endpoints/status.rst .. include:: endpoints/content.rst Possible errors: ---------------- * 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) Sources ------- * `SWORD v2 specification `__ * `arxiv documentation `__ * `Dataverse example `__ * `SWORD used on HAL `__ * `xml examples for CCSD `__