diff --git a/docs/uri-scheme-api-identifiers.rst b/docs/uri-scheme-api-identifiers.rst --- a/docs/uri-scheme-api-identifiers.rst +++ b/docs/uri-scheme-api-identifiers.rst @@ -2,3 +2,6 @@ ---------------------- .. autosimple:: swh.web.api.views.identifiers.api_resolve_swh_pid + +.. autosimple:: swh.web.api.views.identifiers.api_swh_pid_known + diff --git a/swh/web/api/views/identifiers.py b/swh/web/api/views/identifiers.py --- a/swh/web/api/views/identifiers.py +++ b/swh/web/api/views/identifiers.py @@ -22,7 +22,8 @@ Resolve a Software Heritage persistent identifier. - Try to resolve a provided `persistent identifier `_ + Try to resolve a provided `persistent identifier + `_ into an url for browsing the pointed archive object. If the provided identifier is valid, the existence of the object in the archive will also be checked. @@ -30,11 +31,13 @@ :param string swh_id: a Software Heritage persistent identifier :>json string browse_url: the url for browsing the pointed object - :>json object metadata: object holding optional parts of the persistent identifier + :>json object metadata: object holding optional parts of the + persistent identifier :>json string namespace: the persistent identifier namespace :>json string object_id: the hash identifier of the pointed object :>json string object_type: the type of the pointed object - :>json number scheme_version: the scheme version of the persistent identifier + :>json number scheme_version: the scheme version of the persistent + identifier {common_headers} @@ -47,7 +50,7 @@ .. parsed-literal:: :swh_web_api:`resolve/swh:1:rev:96db9023b881d7cd9f379b0c154650d6c108e9a3;origin=https://github.com/openssl/openssl/` - """ # noqa + """ # try to resolve the provided pid swh_id_resolved = resolve_swh_persistent_id(swh_id) # id is well-formed, now check that the pointed @@ -65,22 +68,32 @@ @api_route(r'/known/', - 'api-1-swh-pid-known', methods=['POST']) -@api_doc('/known/', tags=['hidden']) + 'api-1-known', methods=['POST']) +@api_doc('/known/') @format_docstring() def api_swh_pid_known(request): """ .. http:post:: /api/1/known/ - Check if a list of Software Heritage persistent identifier is present - in the archive depending on their id (sha1_git). + Check if a list of objects are present in the Software Heritage + archive. + + The objects to check existence must be provided using Software Heritage + `persistent identifiers + `_. + + :json object : an object whose keys are input persistent + identifiers and values objects with the following keys: - Returns: - A dictionary with: - keys(str): Persistent identifier - values(dict): A dictionary containing the key 'known'. (true if - the pid is present, False otherwise) + * **known (bool)**: whether the object was found + {common_headers} + + :statuscode 200: no error + :statuscode 400: an invalid persistent identifier was provided """ persistent_ids = [get_persistent_identifier(pid) for pid in request.data] diff --git a/swh/web/tests/api/views/test_identifiers.py b/swh/web/tests/api/views/test_identifiers.py --- a/swh/web/tests/api/views/test_identifiers.py +++ b/swh/web/tests/api/views/test_identifiers.py @@ -109,7 +109,7 @@ input_pids = [content_, directory_, unknown_revision_, unknown_release_, unknown_snapshot_] - url = reverse('api-1-swh-pid-known') + url = reverse('api-1-known') resp = api_client.post(url, data=input_pids, format='json', HTTP_ACCEPT='application/json') @@ -129,7 +129,7 @@ invalid_pid_sha1 = ['swh:1:cnt:8068d0075010b590762c6cb5682ed53cb3c13de;'] invalid_pid_type = ['swh:1:cnn:8068d0075010b590762c6cb5682ed53cb3c13deb'] - url = reverse('api-1-swh-pid-known') + url = reverse('api-1-known') resp = api_client.post(url, data=invalid_pid_sha1, format='json', HTTP_ACCEPT='application/json')