docs/_static/discovery/v1.yaml
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:8081
description: For internal-facing endpoints.
paths:
/internal/discovery/v1:
get:
summary: Retrieves the list of Discovery Services.
description: |
An API provided by the Discovery Client that retrieves the list of configured Discovery Services.
operationId: getServices
tags:
- discovery
responses:
"200":
description: List of configured Discovery Services
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ServiceDefinition"
default:
$ref: "../common/error_response.yaml"
/internal/discovery/v1/{serviceID}:
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
required: false
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.
It queries the client's local copy of the Discovery Service which is periodically synchronized with the Discovery Server.
This means new registrations might not immediately show up, depending on the client refresh interval.
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:
$ref: "#/components/schemas/SearchResult"
default:
$ref: "../common/error_response.yaml"
/internal/discovery/v1/{serviceID}/{subjectID}:
description: |
APIs to manage the activation of a DID subject on a Discovery Service.
When a service has been activated for a subject, the Discovery Client will automatically register all qualifying DIDs of that subject on the Discovery Service.
parameters:
- name: serviceID
in: path
required: true
schema:
type: string
- name: subjectID
in: path
description: URL encoded subject.
required: true
content:
plain/text:
schema:
type: string
example: "tenant-123"
get:
summary: Retrieves the activation status of a subject on a Discovery Service.
description: |
An API provided by the Discovery Client,
used to check whether the client is managing the given subject on the specified Discovery Service (service has been activated for the subject)
and the status of the activation. A refresh could have failed.
It will return true after successfully calling the activateServiceForSubject API, and false after calling the deactivateServiceForSubject API.
It also returns the active Verifiable Presentations, if any.
operationId: getServiceActivation
tags:
- discovery
responses:
"200":
description: Success result.
content:
application/json:
schema:
type: object
required:
- activated
- status
properties:
activated:
type: boolean
description: Whether the Discovery Service is activated for the given subject
status:
type: string
description: Status of the activation. "active" or "error".
enum:
- active
- error
error:
type: string
description: Error message if status is "error".
vp:
description: |
List of VPs on the Discovery Service for the subject. One per DID method registered on the Service.
The list can be empty even if activated==true if none of the DIDs of a subject is actually registered on the Discovery Service.
type: array
items:
$ref: "#/components/schemas/VerifiablePresentation"
default:
$ref: "../common/error_response.yaml"
post:
summary: Client API to activate a subject on the specified Discovery Service.
description: |
An API provided by the discovery client that will cause all qualifying DIDs of a subject to be registered on the specified Discovery Service.
A DID qualifies for registration if it meets the requirements defined the Presentation Definition of the Discovery Service.
Registration of all DIDs of a subject will be attempted immediately, and they will be automatically refreshed.
Applications only need to call this API once for every service/subject combination, until the registration is explicitly deleted through this API.
If initial registration fails, this API returns the error indicating what failed and periodically retry registration.
Applications can force a retry by calling this API again.
error returns:
* 400 - incorrect input: invalid/unknown service or subject.
* 412 - precondition failed: subject doesn't have the required credentials.
operationId: activateServiceForSubject
tags:
- discovery
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceActivationRequest'
responses:
"200":
description: Activation was successful.
"400":
$ref: "../common/error_response.yaml"
"412":
$ref: "../common/error_response.yaml"
default:
$ref: "../common/error_response.yaml"
delete:
summary: Client API to deactivate the given subject from the Discovery Service.
description: |
An API provided by the discovery client that will cancel the periodic registration of a subject on the specified Discovery Service.
It will also try to delete all the existing registrations on the Discovery Service, if any.
error returns:
* 400 - incorrect input: invalid/unknown service or subject.
operationId: deactivateServiceForSubject
tags:
- discovery
responses:
"200":
description: |
DID was successfully deactivated from the Discovery Service.
The active Verifiable Presentation was removed from the remote Discovery Server (if applicable).
"202":
description: |
DID was successfully deactivated from the Discovery Service, but failed to remove the active Verifiable Presentation registration from the remote Discovery Server. The registration will be removed by the Discovery Server when the active Verifiable Presentation expires.
Applications might want to retry this API call later, or simply let the presentation expire.
content:
application/json:
schema:
type: object
required:
- reason
properties:
reason:
type: string
description: Description of why removal of the registration failed.
"400":
$ref: "../common/error_response.yaml"
default:
$ref: "../common/error_response.yaml"
components:
schemas:
VerifiablePresentation:
$ref: "../common/ssi_types.yaml#/components/schemas/VerifiablePresentation"
SearchResult:
type: object
required:
- id
- credential_subject_id
- vp
- fields
- registrationParameters
properties:
id:
type: string
description: The ID of the Verifiable Presentation.
credential_subject_id:
type: string
description: The ID of the Verifiable Credential subject (holder), typically a DID.
registrationParameters:
type: object
description: |
Additional parameters used when activating the service.
The authServerURL parameter is always present.
vp:
$ref: "#/components/schemas/VerifiablePresentation"
fields:
type: object
description: Input descriptor IDs and their mapped values that from the Verifiable Credential.
ServiceActivationRequest:
type: object
description: Request for service activation.
properties:
registrationParameters:
type: object
description: |
Additional parameters to use when activating a service. The contents of the object will be placed in the credentialSubject field of a DiscoveryRegistrationCredential.
This, for example, allows use cases to require and clients to register specific endpoints.
The authServerURL parameter is added automatically.
example: |
{
"some-endpoint-type": "https://example.com/some-endpoint"
}
ServiceDefinition:
type: object
required:
- id
- endpoint
- presentation_definition
- presentation_max_validity
properties:
id:
type: string
description: The ID of the Discovery Service.
endpoint:
type: string
description: The endpoint of the Discovery Service.
presentation_definition:
type: object
description: The Presentation Definition of the Discovery Service.
presentation_max_validity:
type: integer
description: The maximum validity (in seconds) of a Verifiable Presentation of the Discovery Service.
securitySchemes:
jwtBearerAuth:
type: http
scheme: bearer
security:
- { }
- jwtBearerAuth: [ ]