openapi: 3.1.0
info:
  title: DVPA-r onboarding test implementation
  description: An implementation of the DVPA-r onboarding interface suitable for testing a client implementation
  version: 0.1.0
servers:
  - url: http://dvpa-r.test.mcsr.nl:4433/onboarding/v1
security:
  - mutualTLS: []
paths:
  /connection:
    post:
      summary: Request a connection with the DVPA-r
      description: |-
        Request a connection with the DVPA-r
      operationId: requestConnection
      requestBody:
        required: true
        description: Connection setup parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionRequestParameters'
      responses:
        '200':
          $ref: '#/components/responses/ConnectionRequestResponse'   
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /connection/{id}: 
    post:
      summary: Complete a pending connection request with the DVPA-r
      description: |-
        Complete a pending connection request with the DVPA-r
      operationId: completeConnectionRequest
      parameters:
        - in: path
          name: id
          required: true
          schema:
            description: The identifier of the to be completed connection request
            type: string
      requestBody:
        required: true
        description: Connection setup parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteConnectionRequestParameters'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          description: Invalid client certificate used
components:
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: Mutual TLS authentication using client certificate
  schemas:
    CompleteConnectionRequestParameters:
      type: object
      description: Parameters for completing the connection reuqest
      properties:
        connectionRequestToken:
          description: |-
            The received connection-request-token
          type: string         
    ConnectionRequestParameters:
      type: object
      description: Information about the requesting organisation, used to validate the request
      properties:
        organisationFormalName:
          description: |-
            Formal name of organisation that controls the HAPIS as subscribed with the KvK
          type: string         
        organisationIdentifier:
          description: |-
            Identifier for the organisation that controls the HAPIS
          type: string 
        organisationIdentifierType:
          description: |-
            Type of identifier used as organisationIdentifier; e.g. AGB-code or Kvk-number
          type: string
  responses:
    ConnectionRequestResponse:
      description: |-
        Return value for a connection request used in the onboarding procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              connectionRequestIdentifier:
                type: string
                description: An unique identifier for this connection request, used by the HAPIS when it tries to complete this connection
    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"