openapi: 3.1.0
info:
  title: DVPA-r test implementation
  description: An implementation of the DVPA-r interface suitable for testing a client implementation
  version: 0.1.0
servers:
  - url: https://dvpa-r.test.mcsr.nl:4433/dvpa-r/v1
security:
  - mutualTLS: []
paths:
  /authorizations:
    get:
      summary: Search authorizations
      parameters:
        - in: query
          name: patientRecordType
          schema:
            description: Type of the associated patient record
            type: string
          example: PS
        - in: query
          name: patientRecordFormat
          schema:
            description: Format of the associated patient record
            type: string
          example: HL7v3
        - in: query
          name: patientBsn
          schema:
            description: The patient's BSN
            type: string
          example: '99998882'
        - in: query
          name: patientName
          schema:
            description: The patient's full name
            type: string
          example: Jan+K.+Test
        - in: query
          name: patientBirthdate
          schema:
            description: The patient's date of birth (in yyyy-mm-dd format)
            type: string
          example: '1977-02-03'
        - in: query
          name: patientStreet
          schema:
            description: The patient's streetname
            type: string
          example: Notenlaan
        - in: query
          name: patientHouseNumber
          schema:
            description: The patient's housenumber
            type: string
          example: 56a
        - in: query
          name: patientPostalCode
          schema:
            description: The patient's postalcode (in 1234AA format)
            type: string
          example: 3345CC
        - in: query
          name: patientCity
          schema:
            description: The patient's city
            type: string
          example: Volendam
        - in: query
          name: patientGender
          schema:
            description: The patient's gender
            type: string
            enum: [male, female, unknown, other]
          example: male
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfAuthorizations'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          description: No patient records found that match the provided search criteria
    post:
      summary: Instantiate authorization
      parameters:
        - in: query
          name: patientRecordType
          schema:
            description: Type of the associated patient record
            type: string
          example: PS
        - in: query
          name: patientRecordFormat
          schema:
            description: Format of the associated patient record
            type: string
          example: HL7v3
        - in: query
          name: patientBsn
          schema:
            description: The patient's BSN
            type: string
          example: '99998882'
        - in: query
          name: patientName
          schema:
            description: The patient's full name
            type: string
          example: Jan+K.+Test
        - in: query
          name: patientBirthdate
          schema:
            description: The patient's date of birth (in yyyy-mm-dd format)
            type: string
          example: '1977-02-03'
        - in: query
          name: patientStreet
          schema:
            description: The patient's streetname
            type: string
          example: Notenlaan
        - in: query
          name: patientHouseNumber
          schema:
            description: The patient's housenumber
            type: string
          example: 56a
        - in: query
          name: patientPostalCode
          schema:
            description: The patient's postalcode (in 1234AA format)
            type: string
          example: 3345CC
        - in: query
          name: patientCity
          schema:
            description: The patient's city
            type: string
          example: Volendam
        - in: query
          name: patientGender
          schema:
            description: The patient's gender
            type: string
            enum: [male, female, unknown, other]
          example: male
      responses: 
        '201':
          description: Created
        '404':
          description: No patient records found that match the provided search criteria
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /authorizationInstances/{id}:
    get:
      summary: Inspect a authorizationInstance
      parameters:
        - in: path
          required: true
          name: id
          schema:
            description: The authorization's id
            type: string
      responses: 
        '404':
          description: No authorizationInstance found with the provided id
        '200':
          $ref: '#/components/responses/GetAuthorizationInstanceResponse'
  /authorizationInstances/{id}/token-data:
    get:
      summary: Retrieve a partially prefilled template of which a token can be constructed which is needed to perform further actions on the authorizationInstance
      parameters:
        - in: path
          required: true
          name: id
          schema:
            description: The authorization instance's id
            type: string
      responses:
        '200':
          $ref: '#/components/responses/GetTokenTemplateResponse'
        '404':
          description: No authorizationInstance found with the provided id
  /authorizationInstances/{id}/patient-record:
    get:
      summary: Retrieve the underlying patient record for a authorizationInstance
      parameters:
        - in: path
          required: true
          name: id
          schema:
            description: The authorization instance's id
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          description: Authorization failed
        '404':
          description: No authorizationInstance found with the provided id
  /messages:
    get:
      summary: Search transfermessages
      parameters:
        - in: query
          name: patientBsn
          schema:
            description: The patient's BSN
            type: string
          example: '99998882'
      responses:
        '404':
          description: No transfermessages found
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfTransferMessages'
  /messages/{id}:
    get:
      summary: Retrieve transfermessage by id
      parameters:
        - in: path
          required: true
          name: id
          schema:
            description: The message's local id
            type: string
      responses: 
        '404':
          description: No transfermessage found with the provided id
        '200':
          description: OK
    delete:
      summary: delete transfermessage by id
      parameters:
        - in: path
          required: true
          name: id
          schema:
            description: The message's local id
            type: string
      responses:
        '404':
          description: No transfermessages found
        '204':
          description: No content
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: WhiteboxJWT
    mutualTLS:
      type: mutualTLS
      description: Mutual TLS authentication using client certificate
  schemas:
    Patient:
      type: object
      properties:
        registrationDate:
          description: The patient's registration date
          type: number
        bsn:
          description: The patient's BSN
          type: string
        name:
          description: The patient's full name
          type: string
        birthdate:
          description: The patient's date of birth (in yyyy-mm-dd format)
          type: string
        city:
          description: The patient's city
          type: string
        gender:
          description: The patient's gender
          type: string
        street:
          description: The patient's streetname
          type: string
        houseNumber:
          description: The patient's housenumber
          type: string
        postalCode:
          description: The patient's postalcode (in 1234AA format)
          type: string
    AuthorizationSource:
      type: object
      properties:
        systemUrl:
          type: string
        organisationName:
          type: string
    Authorization:
      type: object
      properties:
        authorizationId:
          type: string
        authorizationType:
          type: string
        source:
          $ref: '#/components/schemas/AuthorizationSource'
        patientRecordType:
          type: string
        patientRecordFormats:
          type: array
          items:
            type: string
        pushbackTypes:
          type: array
          items:
            type: string
        expiresAt:
          type: string
        patient:
          $ref: '#/components/schemas/Patient'
    ListOfAuthorizations:
      type: array
      items:
        $ref: '#/components/schemas/Authorization'
    AuthorizationInstance:
      description: Instance of an authorization which can de used to retrieve the underlying patient record
      type: object
      properties:
        createdOn:
          description: Epoch Unix timestamp of when this instance was created
          type: number
        authorizationId:
          description: Identifier of the authorization this resource is an instance of
          type: string
        instanceId:
          description: Identifier of this specific instance
          type: string
        state:
          description: Indicates in which state this instance currently is in
          type: string
          enum: [ready, bound, expired, invalidated]
        boundToType:
          type: string
          description: |-
            A PA-URL can be bound to several properties, depending on context: a key or certificate fingerprint, a common name (implicitly assuming a CA or identity management system to validate the idenity purveyed by this name), a UZI-ID. etc. boundToType indicates what property or properties a PA-URL is bound to (e.g., organization name ("CN"), organization URA ("URA"), healthcare professional UZI ("UZI"), key fingerprint, etc.)
        boundTo:
          type: object
          description: |-
            Depending on boundToType, boundTo contains the actual information that a PA-URL is bound to; the boundTo object is represented as a JSON struct with always at least the properties subject (to contain a key fingerprint, an uzi-id etc), and a description. Depending on boundToType, this JSON struct may be extended.
          properties:
            subject:
              type: string
              description: The actual value of the property this instance is bound to. E.g. the actual key-fp or uzi-id
            description:
              type: string
              description: (Human-readable) name of the subject, typically the CN as present on a UZI pass.
        expiresAt:
          description: Epoch Unix timestamp of when this instance was created
          type: number
    WBXTokenClaims:
      type: object
      properties:
        url:
          description: The actual underlying PA-URL
          type: string
        challenge:
          description: The challenge that is linked to the PA-URL, Whitebox specific implementation detail
          type: string
        timestamp:
          description: Epoch Unix timestamp of the moment of signing
          type: string
        authorizationSubject:
          description: BSN of patient of whom the patient record holds data
          type: string
        user:
          description: A JSON object contaning information about the user that tries to retrieve information with this authorization
          type: object
          properties:
            uzi_id:
              description: UZI id contained in UZI-card certificate
              type: string
            uzi_ura:
              description: URA contained in UZI-card certificate
              type: string
        system:
          description: Information about the DVPA-r
          type: object
          properties:
            key_fp:
              description: Fingerprint of DVPA-r's system certificate
              type: string
    TokenTemplateWBXJWTData:
      type: object
      properties:
        allowedAlg:
          type: array
          items:
            type: string
        header:
          type: object
          properties:
            x5c:
              description: Certificate chain of UZI certificate which is used to sign this token in PEM format (excluding UZI-register CA)
              type: string
            alg:
              description: Type of algoritm used for the signing of this JWT
              type: string
        claims:
          $ref: '#/components/schemas/WBXTokenClaims'
    TokenTemplate:
      type: object
      description: Template that holds data about the to be signed token for a specific authorizationInstance
      properties:
        toComplement:
          description: |-
            The toComplement property holds a list of of JSON pointers (https://www.rfc-editor.org/rfc/rfc6901) to properties that need to be complemented by the client
          type: array
          items:
            type: string
        tokenType:
          description: |-
            The tokenType is the type of the to be created token. Currently, only "JWT" is supported. The format refers to the general shape of the data property. For instance the "JWT" format indicates that the data property contains the 'allowedAlg', 'header' and 'claims' members. The tokenType also dictates how the token needs to be constructed.
          type: string
          enum: [JWT]
        tokenSubtype:
          description: |-
            The tokenSubType indicates which fields the various data properties have. Currently only "WhiteboxJWT" is supported. The "WhiteboxJWT" subtype indicates that the data.claims property o.a. contains the 'url' and 'challenge' properties.
          type: string
          enum: [WhiteboxJWT]
        data:
          $ref: '#/components/schemas/TokenTemplateWBXJWTData'
    TransferMessage:
      type: object
      description: Transfer message (overdrachtsbericht)
      properties:
        id:
          description: |-
            Unique identifier for this message
          type: string
        senderId:
          description: |-
            Unique identifier assigned by the sender
          type: string
        subjectBsn:
          description: |-
            BSN of subject (patient) of this message
          type: string
        date:
          description: |-
            Epoch Unix timestamp of when this event occured
          type: string
        sender:
          description: |-
            Name of the sender of this message
          type: string
        senderOrganisation:
          description: |-
            Name of the sender's organisation
          type: string
        messageFormat:
          description: |-
            MIMEtype that indicates the type of content the message field contains. For now the only supported MIMEtype is 'text/plain;charset=UTF-8'
          type: string
        message:
          description: |-
            Raw message data
          type: string
    ListOfTransferMessages:
      type: array
      items:
        $ref: '#/components/schemas/TransferMessage' 
  responses:
    ErrorResponse:
      description: |
        Default return values follow Problem Details for HTTP APIs as specified in [RFC7807](https://tools.ietf.org/html/rfc7807).

        Currently, return values contain the following members of a problem details object:
        - "type" (string) - A URI reference [RFC3986] that identifies the problem type.
        - "title" (string) - A short, human-readable summary of the problem type.
        - "status" (number) - The HTTP status code generated by the origin server for this occurrence of the problem.
        - "detail" (string) - A human-readable explanation specific to this occurrence of the problem.
      content:
        application/problem+json:  # https://tools.ietf.org/html/rfc7807#section-6.1
          schema:
            type: object
            required:
              - type
              - title
              - status
              - detail
            properties:
              type:
                type: string
                description: A URI reference [RFC3986] that identifies the problem type.
              title:
                type: string
                description: A short, human-readable summary of the problem type.
              status:
                type: number
                description: HTTP statuscode
              detail:
                type: string
                description: A human-readable explanation specific to this occurrence of the problem.
            example:
              type: "https://docs.whiteboxsystems.nl/dvpa-r/docs/errors#multiple-matches"
              title: "Multiple matches were found"
              status: 400
              detail: "Multiple matches were found, query evalutation must result in exactly one match"
    GetAuthorizationInstanceResponse:
      description: Instance of an authorization which can de used to retrieve the underlying patient record
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthorizationInstance'
    GetTokenTemplateResponse:
        description: Retrieve a partially prefilled template of which a token can be constructed which is needed to perform further actions on the authorizationInstance
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenTemplate'