Discovery: OpenAPI spec for server and client (#2584)

docs/_static/discovery/v1.yaml

@@ -0,0 +1,158 @@
+openapi: "3.0.0"
+info:
+  title: Nuts Discovery Service API spec
+  description: API specification for discovery services available within Nuts node
+  version: 1.0.0
+  license:
+    name: GPLv3
+servers:
+  - url: http://localhost:1323
+paths:
+  /discovery/{serviceID}:
+    parameters:
+      - name: serviceID
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Retrieves the presentations of a discovery service.
+      description: |
+        An API provided by the discovery server to retrieve the presentations of a discovery service, starting at the given timestamp.
+        The client should provide the timestamp it was returned in the last response.
+        If no timestamp is given, it will return all presentations.
+
+        error returns:
+        * 404 - unknown service ID
+      operationId: getPresentations
+      tags:
+        - discovery
+      parameters:
+        - name: timestamp
+          in: query
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Presentations are returned, alongside the timestamp which should be provided at the next query.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - timestamp
+                  - entries
+                properties:
+                  timestamp:
+                    type: string
+                  entries:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/VerifiablePresentation"
+        default:
+          $ref: "../common/error_response.yaml"
+    post:
+      summary: Register a presentation on the discovery service.
+      description: |
+        An API provided by the discovery server that adds a presentation to the service.
+        The presentation must be signed by subject of the credentials it contains.
+        
+        To delete a presentation, the client should send an empty presentation that:
+        * has a JWT claim 'retracted_jti' indicating the ID of the previous presentation of the same subject
+        * has no credentials in it
+        * has the type 'RetractedVerifiablePresentation'
+        
+        error returns:
+        * 400 - incorrect input; e.g. unsupported presentation or credential type, invalid signature, unresolvable credential subject, etc.
+      operationId: registerPresentation
+      tags:
+        - discovery
+      requestBody:
+        description: The presentation to register to the discovery service.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VerifiablePresentation"
+      responses:
+        "201":
+          description: Presentation was registered on the discovery service.
+        "400":
+          $ref: "../common/error_response.yaml"
+        default:
+          $ref: "../common/error_response.yaml"
+  /discovery/{serviceID}/search:
+    parameters:
+      - name: serviceID
+        in: path
+        required: true
+        schema:
+          type: string
+      # Way to specify dynamic query parameters
+      # See https://stackoverflow.com/questions/49582559/how-to-document-dynamic-query-parameter-names-in-openapi-swagger
+      - in: query
+        name: query
+        schema:
+          type: object
+          additionalProperties:
+            type: string
+        style: form
+        explode: true
+    get:
+      summary: Searches for presentations registered on the discovery service.
+      description: |
+        An API of the discovery client that searches for presentations on the discovery service,
+        whose credentials match the given query parameter.
+        The query parameters are interpreted as JSON path expressions, evaluated on the verifiable credentials.
+        The following features and limitations apply:
+        - only simple child-selectors are supported (so no arrays selectors, script expressions etc).
+        - only JSON string values can be matched, no numbers, booleans, etc.
+        - wildcard (*) are supported at the start and end of the value
+        - a single wildcard (*) means: match any (non-nil) value
+        - matching is case-insensitive
+        - expressions must not include the '$.' prefix, which is added by the API.
+        - all expressions must match a single credential, for the credential to be included in the result.
+        - if there are multiple credentials in the presentation, the presentation is included in the result if any of the credentials match.
+        
+        Valid examples:
+        - `credentialSubject.givenName=John`
+        - `credentialSubject.organization.city=Arnhem`
+        - `credentialSubject.organization.name=Hospital*`
+        - `credentialSubject.organization.name=*clinic`
+        - `issuer=did:web:example.com`
+      operationId: searchPresentations
+      tags:
+        - discovery
+      responses:
+        "200":
+          description: Search results are returned, if any.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  required:
+                    - id
+                    - credential
+                  properties:
+                    id:
+                      type: string
+                      description: The ID of the Verifiable Presentation.
+                    credential:
+                      type: object
+                      description: The Verifiable Credential that matched the query.
+        default:
+          $ref: "../common/error_response.yaml"
+components:
+  schemas:
+    VerifiablePresentation:
+      $ref: "../common/ssi_types.yaml#/components/schemas/VerifiablePresentation"
+  securitySchemes:
+    jwtBearerAuth:
+      type: http
+      scheme: bearer
+
+security:
+  - { }
+  - jwtBearerAuth: [ ]