From 2842b890243f8e80f0514bc6708a99ec9a1ac0dd Mon Sep 17 00:00:00 2001 From: reinkrul Date: Wed, 6 Dec 2023 06:05:04 +0100 Subject: [PATCH] Discovery: OpenAPI spec for server and client (#2584) --- docs/_static/discovery/v1.yaml | 158 +++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/_static/discovery/v1.yaml diff --git a/docs/_static/discovery/v1.yaml b/docs/_static/discovery/v1.yaml new file mode 100644 index 0000000000..a79302af01 --- /dev/null +++ b/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: [ ]