Add list curation endpoints to openapi spec and restapi.rst

Author: kkaris

doc/rest_api_doc/rest_api.rst

@@ -24,7 +24,8 @@ following endpoints for getting Statements:
 
 The API also supports curating Statements via the
 :ref:`curation endpoint <curation>`, helping us improve the quality and accuracy
-of our content.
+of our content. You can also list curations (all, or by statement or evidence)
+via the :ref:`curation list endpoints <curation-list-all>`.
 
 You will optionally need the following information to access a running web service:
 
@@ -306,11 +307,46 @@ JSON data should contain the following fields:
 - **curator**: Your name, initials, email, or other way to identify yourself.
   Whichever you choose, please be consistent.
 
-Note that you can also indicate that a Statement is _correct_. In particular,
+Note that you can also indicate that a Statement is *correct*. In particular,
 if you find that a Statement has some evidence that supports the Statement and
 some that does not, curating examples of both is valuable. In general, flagging
 correct Statements can be just as valuable as flagging incorrect Statements.
 
+.. _curation-list-all:
+
+List all curations
+------------------
+
+.. openapi:: ../../indra_db_service/static/openapi.yaml
+   :paths: /curation/list
+
+This authenticated endpoint returns all curations in the database. Curator
+names are anonymized if the caller does not have the correct permissions.
+Authentication is done via an API key in the query parameters.
+
+.. _curation-list-stmt:
+
+List curations for a statement
+------------------------------
+
+.. openapi:: ../../indra_db_service/static/openapi.yaml
+   :paths: /curation/list/{stmt_hash}
+
+This public endpoint returns curations for the given pre-assembly statement
+hash. Authentication is not required for this endpoint.
+
+.. _curation-list-stmt-src:
+
+List curations for a statement and evidence
+-------------------------------------------
+
+.. openapi:: ../../indra_db_service/static/openapi.yaml
+   :paths: /curation/list/{stmt_hash}/{src_hash}
+
+This public endpoint returns all curations for a given statement and evidence. 
+The curations are filtered by both the statement hash and the source (evidence) hash.
+Authentication is not required for this endpoint.
+
 Usage examples
 ==============
 

indra_db_service/static/openapi.yaml

@@ -190,6 +190,82 @@ paths:
               schema:
                 $ref: '#/components/schemas/CurationSubmitResponse'
 
+  /curation/list:
+    get:
+      summary: List all curations
+      description: |
+        This authenticated endpoint returns all curations in the database. Curator
+        names are anonymized if the caller does not have the correct permissions.
+        Authentication is done via an API key in the query parameters.
+      operationId: listAllCurations
+      parameters:
+        - $ref: '#/components/parameters/ApiKeyParam'
+      responses:
+        '200':
+          description: List of all curations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CurationListEntry'
+
+  /curation/list/{stmt_hash}:
+    get:
+      summary: List curations for a statement
+      description: |
+        Public endpoint. Returns curations for the given pre-assembly statement hash.
+        Authentication is not required for this endpoint.
+      operationId: listCurationsForStatement
+      parameters:
+        - name: stmt_hash
+          in: path
+          required: true
+          description: Pre-assembly statement hash (pa level).
+          schema:
+            type: string
+            example: "-1072112758478440"
+      responses:
+        '200':
+          description: List of curations for the statement
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CurationListEntry'
+
+  /curation/list/{stmt_hash}/{src_hash}:
+    get:
+      summary: List curations for a statement and evidence
+      description: |
+        Public endpoint. Returns curations filtered by both statement hash and
+        source (evidence) hash. Authentication is not required for this endpoint.
+      operationId: listCurationsForStatementAndSource
+      parameters:
+        - name: stmt_hash
+          in: path
+          required: true
+          description: Pre-assembly statement hash (pa level).
+          schema:
+            type: string
+            example: "-1072112758478440"
+        - name: src_hash
+          in: path
+          required: true
+          description: Source (evidence) hash for raw-level curations.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of curations for the statement and evidence
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CurationListEntry'
+
 components:
   parameters:
     FormatParam:
@@ -372,3 +448,38 @@ components:
             id:
               type: integer
               description: Database id of the submitted curation.
+
+    CurationListEntry:
+      type: object
+      description: A single curation record as returned by the list endpoints.
+      properties:
+        curator:
+          type: string
+          description: Curator email (may be anonymized if caller lacks get_curations permission).
+        date:
+          type: string
+          description: Timestamp in HTTP date format (e.g. Thu, 29 Nov 2018 18:00:08 GMT).
+        ev_json:
+          type: string
+          description: Optional evidence JSON (serialized).
+        id:
+          type: integer
+          description: id of the curation.
+        pa_hash:
+          type: integer
+          description: Pre-assembly statement hash.
+        pa_json:
+          type: string
+          description: Optional pre-assembly statement JSON (serialized).
+        source:
+          type: string
+          description: Source of the curation submission (e.g. DB REST API).
+        source_hash:
+          type: integer
+          description: Source (evidence) hash for raw-level curations.
+        tag:
+          type: string
+          description: Short category for the curation (e.g. grounding, correct).
+        text:
+          type: string
+          description: Optional brief description of the curation.