api/identifiers: Add /known/ endpoint documentation

docs/uri-scheme-api-identifiers.rst

@@ -2,3 +2,6 @@ Persistent identifiers
 ----------------------
 
 .. autosimple:: swh.web.api.views.identifiers.api_resolve_swh_pid
+
+.. autosimple:: swh.web.api.views.identifiers.api_swh_pid_known
+

swh/web/api/views/identifiers.py

@@ -23,7 +23,8 @@ def api_resolve_swh_pid(request, swh_id):
 
         Resolve a Software Heritage persistent identifier.
 
-        Try to resolve a provided `persistent identifier <https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html>`_
+        Try to resolve a provided `persistent identifier
+        <https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html>`_
         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.
@@ -31,11 +32,13 @@ def api_resolve_swh_pid(request, swh_id):
         :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}
 
@@ -48,7 +51,7 @@ def api_resolve_swh_pid(request, swh_id):
         .. 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
@@ -66,21 +69,33 @@ def api_resolve_swh_pid(request, swh_id):
 
 
 @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
+        <https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html>`_.
+
+        :<jsonarr string -: input array of Software Heritage persistent
+            identifiers, its length can not exceed 1000.
+
+        :>json object <swh_pid>: 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
+        :statuscode 413: the input array of persistent identifiers is too large
 
     """
     limit = 1000

swh/web/tests/api/views/test_identifiers.py

@@ -109,7 +109,7 @@ def test_api_known_swhpid_some_present(api_client, content, directory):
     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 @@ def test_api_known_invalid_swhpid(api_client):
     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')
@@ -149,7 +149,7 @@ def test_api_known_raises_large_payload_error(api_client):
 
     pids = [random_pid for i in range(limit)]
 
-    url = reverse('api-1-swh-pid-known')
+    url = reverse('api-1-known')
     resp = api_client.post(url, data=pids, format='json',
                            HTTP_ACCEPT='application/json')