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// +.. 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 : 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 --- a/docs/endpoints/content.rst +++ b/docs/endpoints/content.rst @@ -1,7 +1,7 @@ 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. @@ -9,6 +9,67 @@ 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 --- 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 : 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 --- a/docs/endpoints/status.rst +++ b/docs/endpoints/status.rst @@ -1,7 +1,7 @@ Retrieve status ^^^^^^^^^^^^^^^^ -.. http:get:: /1/// +.. 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 : 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 @@ 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 @@ -72,3 +52,30 @@ 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 --- a/docs/endpoints/update-media.rst +++ b/docs/endpoints/update-media.rst @@ -1,12 +1,12 @@ 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. @@ -14,13 +14,13 @@ 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 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///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. @@ -14,10 +14,10 @@ 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 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)