[ATL-1388] doc(pollux): add Revocation Registry API, remove v1 from t…

…he path, apply changes after review (#14)

* doc(pollux): add Revocation Registry API, removed v1 from the path

* doc(pollux): add 'present-proof' controlled and 'verifiable-presentation collection' API

* doc(pollux): apply the changes after review

pollux/api/pollux-openapi-spec.yaml

@@ -17,11 +17,13 @@ tags:
     description: Verifiable Credentials creation and issuance REST API
   - name: Verify Credentials
     description: Verifiable Credentials verification REST API
-  - name: Revoke Credentials
+  - name: Revocation
     description: Verifiable Credentials revocation REST API
+  - name: Present Proof
+    description: Present Proof REST API
 
 paths:
-  /schema-registry/v1/schemas:
+  /schema-registry/schemas:
     post:
       tags: ["Schema Registry"]
       operationId: createSchema
@@ -36,12 +38,6 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/W3CSchemaInput"
-            example:
-              name: ""
-              version: "1.0"
-              claims:
-                - name: "email"
-                  type: "string"
       responses:
         "201":
           description: The new schema is created
@@ -91,7 +87,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/W3CSchemaPaginated"
-  /schema-registry/v1/schemas/{id}:
+  /schema-registry/schemas/{id}:
     get:
       tags: ["Schema Registry"]
       operationId: getSchemaById
@@ -116,7 +112,7 @@ paths:
         "404":
           description: Schema is not found by id
 
-  /issue-credentials/v1/credentials:
+  /issue-credentials/credentials:
     post:
       tags: ["Issue Credentials"]
       operationId: createCredentials
@@ -197,8 +193,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/W3CCredentialsPaginated"
-
-  /issue-credentials/v1/credentials/{id}:
+  /issue-credentials/credentials/{id}:
     get:
       tags: ["Issue Credentials"]
       operationId: getCredentialById
@@ -263,8 +258,7 @@ paths:
       responses:
         "204":
           description: "Credential was deleted"
-
-  /issue-credentials/v1/issuance-batches:
+  /issue-credentials/issuance-batches:
     get:
       tags: ["Issue Credentials"]
       operationId: getIssuanceBatches
@@ -286,8 +280,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/W3CIssuanceBatchPaginated"
-
-  /issue-credentials/v1/issuance-batches/{batchId}/actions:
+  /issue-credentials/issuance-batches/{batchId}/actions:
     post:
       tags: ["Issue Credentials"]
       summary: "Submit the list of actions performed on the credentials associated with the issuance-batch"
@@ -341,6 +334,146 @@ paths:
                 items:
                   $ref: "#/components/schemas/W3CIssuanceBatchAction"
 
+  /revocation-registry/credential-status/{id}:
+    get:
+      tags: ["Revocation Registry"]
+      operationId: getCredentialRevocationStatusById
+      summary: Get credentials revocation status by credential id
+      description: Get credentials revocation status by credential id
+      parameters:
+        - in: path
+          name: id
+          description: Verifiable Credential Id
+          schema:
+            type: string
+          required: true
+          example: "abcde12345"
+      responses:
+        "200":
+          description: Status request processed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/W3CCredentialStatus"
+  /revocation-registry/revoke:
+    post:
+      tags: ["Revocation Registry"]
+      operationId: revokeCredentialById
+      summary: Revoke credential by id
+      description: Revoke credential by id
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/W3CCredentialRevocationRequest"
+      responses:
+        "202":
+          description: Revocation request successfully submitted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/W3CCredentialRevocationResponse"
+          headers:
+            Location:
+              schema:
+                type: string
+              description: URL to access credential revocation status.
+
+  /revocation-registry/operations/{id}:
+    get:
+      tags: ["Revocation Registry"]
+      operationId: getRevocationOperationStatusById
+      summary: Get revocation operation status by id
+      description: Get revocation operation status by id
+      parameters:
+        - in: path
+          name: id
+          schema:
+            type: string
+          required: true
+      responses:
+        "200":
+          description: Success, operation status is returned
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RevocationStatus"
+
+  /present-proof/verifiable-presentations:
+    post:
+      tags: ["Present Proof"]
+      operationId: createVerifiablePresentation
+      summary: Create new instance of VerifiablePresentation
+      description: Verifier creates the instance of Verifiable Presentation object to be used in present proof communication protocol with Prover
+      requestBody:
+        description: PresentationInput object with the schema references and claims
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/W3CPresentationInput"
+      responses:
+        "201":
+          description: The new presentation is created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/W3CPresentation"
+        # TODO: Add other corner cases and error responses
+
+    get:
+      tags: ["Present Proof"]
+      operationId: fetchPresentationByQuery
+      summary: Fetch presentation by query
+      description: Fetch presentation by query
+      parameters: # TODO: Define the parameters for the presentation lookup
+        - in: query
+          name: name
+          description: Fetch presentation by the name
+          example: TemplateName
+          schema:
+            type: string
+        - in: query
+          name: offset
+          description: Pagination offset
+          example: 15
+          schema:
+            type: integer
+        - in: query
+          name: limit
+          description: Pagination limit
+          example: 100
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Presentations are fetched by the query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/W3CPresentationPaginated"
+  /present-proof/verifiable-presentations/{id}:
+    get:
+      tags: ["Present Proof"]
+      operationId: getPresentationById
+      summary: Fetch the presentation from the collection by id
+      description: Fetch the presentation from the collection by id
+      parameters:
+        - in: path
+          name: id
+          schema:
+            type: string
+          required: true
+          description: Unique identifier of the presentation
+          example: "06e126d1-fa44-4882-a243-1e326fbe21db"
+      responses:
+        "200":
+          description: Successful response, the presentation is returned
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/W3CPresentation"
+
 components:
   schemas:
     W3CProof:
@@ -389,18 +522,15 @@ components:
         description:
           type: string
           description: Schema description
-        claims:
+        attributes:
           type: "array"
-          description: "List of claims"
+          description: List of attributes
           items:
-            type: "object"
-            properties:
-              name:
-                type: "string"
-                description: "Name of the claim attribute"
-              type:
-                type: "string"
-                description: "Type of the claim attribute (bool, string, datetime, integer)"
+            type: "string"
+          example:
+            - first_name
+            - last_name
+            - date_of_birth
 
     W3CSchemaMeta:
       description: Schema metadata
@@ -600,3 +730,87 @@ components:
           type: integer
         count:
           type: integer
+
+    W3CCredentialStatus:
+      description: Verifiable Credential revocation status
+      required:
+        - status
+      properties:
+        status:
+          description: Status name
+          type: string
+          enum:
+            - issued
+            - revoked
+          example: "issued"
+        description:
+          type: string
+          description: Description about the status
+          example: "Issued by did:prism:issuer12354 on 2022-02-01"
+
+    W3CCredentialRevocationRequest:
+      description: Credential revocation request. Contain credential id and other information required for revocation
+      required:
+        - credentialId
+      additionalProperties: true
+      properties:
+        credentialId:
+          type: string
+          description: Credential identity
+          example: "abcde-12345"
+
+    W3CCredentialRevocationResponse:
+      description: Credential revocation response. Contain credential id and revocation operation for tracing the completion
+      required:
+        - credentialId
+        - operationId
+        - status
+      properties:
+        credentialId:
+          type: string
+          description: Credential identity
+          example: "abcde-12345"
+        operation:
+          $ref: "#/components/schemas/RevocationStatus"
+
+    RevocationStatus:
+      description: Revocation status record
+      properties:
+        id:
+          type: string
+          description: Operation id
+          example: "operation1235"
+        status:
+          type: string
+          description: Operation status
+          enum:
+            - scheduled
+            - pending
+            - completed
+            - failed
+
+    W3CPresentationInput:
+      description: Verifiable Presentation input
+      properties:
+        schemas:
+          type: string # TODO: Define the schema for Presentation Input
+
+    W3CPresentation:
+      description: Verifiable Presentation object
+      properties:
+        schemas:
+          type: string # TODO: define the exactly schema for Presentation
+
+    W3CPresentationPaginated:
+      description: "Paginated response that contains an array of the presentation objects"
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/W3CPresentation"
+        offset:
+          type: integer
+        limit:
+          type: integer
+        count:
+          type: integer