openapi: 3.0.1
info:
  title: Ozone Connect - Health Check APIs
  contact:
    name: Ozone Financial Technology Limited
  description: >
    This document provides an API description in [OpenAPI](https://spec.openapis.org/oas/v3.0.1.html) for Health Check
    APIs for Ozone Connect.


    These APIs should be implemented by an financial institution so that Ozone

    can ensure that the institution's Ozone Connect implementation is up and running.


    Please refer to the API Hub documentation for details of test cases that are

    available for this API using the Ozone Connect test suite.


    ### Versioning


    The `version` property implements the following pattern
    `{standards-major}.{standards-minor}.{ozone-connect-version}`, where:


    * `standards-major` is the major version of the latest UAE standard that the API description implements.

    * `standards-minor` is the minor version of the latest UAE standard that the API description implements.

    * `ozone-connect-version` is the version of the Ozone Connect API description.


    So, for example, `v2.0.1` indicates the first version of the Ozone Connect API description that implements the UAE
    standard version 2.0.

    ### v2.1.2

    * Changed the `HealthCheckCertResponse.clientCertificate.subject` description and example. The endpoint echoes 
      the client certificate presented by the caller during the mTLS handshake; for Open Finance UAE callers the `OU` 
      carries the caller's organisation ID from the Trust Framework directory, not a DNS name in the `CN`. Refreshed 
      the `issuer` example to the Sandbox Trust Framework issuing CA for symmetry.

  version: v2.1.2
servers:
  - url: https://<your-ozone-connect-server>
tags:
  - name: health-check
    description: APIs that should be implemented by Financial Institutions to expose health check operations
security:
  - {}
paths:
  /hello:
    get:
      operationId: hello
      summary: check connectivity without a mutual tls check
      tags:
        - health-check
      description: >
        Check connectivity without a mutual tls CheckDetails.

        This health check is used to check that the end-to-end network connectivity is working as expected. This is a
        simple health check that does not require mutual TLS.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheck200Response'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
  /hello-mtls:
    get:
      operationId: helloMtls
      summary: check connectivity including mtls
      tags:
        - health-check
      description: >
        Check connectivity including mutual TLS CheckDetails.

        This health check is used to check that the end-to-end network connectivity is working as expected including
        mutual tls.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheck200Response'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
  /echo-cert:
    get:
      operationId: echoCert
      tags:
        - health-check
      summary: Provides information about the client cert that the server received
      description: >
        This health check endpoint assists in debugging mutual tls client issues.

        The health check returns information about the client certificate and the issuer of the client certificate that
        the server received.

        Where mtls cannot be established, the server will return a 401 response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckCertResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
components:
  responses:
    UnauthorizedResponse:
      description: Unauthorized response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HealthCheck4xxResponse'
    DefaultErrorResponse:
      description: Default error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HealthCheck4xxResponse'
  schemas:
    HealthCheck200Response:
      type: object
      description: Successful response on a health check
      properties:
        connectionEstablished:
          $ref: '#/components/schemas/ConnectionEstablished'
        mtlsStatus:
          description: Describes the status of the mTLS connection
          type: string
          enum:
            - established
            - not-established
            - not-checked
        hostName:
          $ref: '#/components/schemas/HostName'
      required:
        - connectionEstablished
        - mtlsStatus
        - hostName
    HealthCheck4xxResponse:
      type: object
      description: Response when connection could not be established
      properties:
        errorMessage:
          description: A description of the error being experienced.
          type: string
      required:
        - errorMessage
    HealthCheckCertResponse:
      type: object
      properties:
        connectionEstablished:
          $ref: '#/components/schemas/ConnectionEstablished'
        mtlsStatus:
          type: string
          enum:
            - established
            - not-established
        hostName:
          $ref: '#/components/schemas/HostName'
        clientCertificate:
          description: Properties of the client certificate presented by the caller during the mTLS handshake.
          type: object
          properties:
            subject:
              description: >-
                The Distinguished Name of the client certificate's subject. For Open Finance UAE callers, the OU
                contains the caller's organisation ID from the Trust Framework directory.
              type: string
              example: C=UK, O=OZONE FINANCIAL TECHNOLOGY LIMITED, OU=233bcd1d-4216-4b3c-a362-9e4a9282bba7
            issuer:
              description: The Distinguished Name of the issuing Certificate Authority.
              type: string
              example: C=AE, O=Open Finance UAE, OU=Open Finance UAE Sandbox Trust Framework, CN=Open Finance UAE 
                Sandbox Issuing CA - G1
          required:
            - subject
            - issuer
      required:
        - connectionEstablished
        - mtlsStatus
        - hostName
        - clientCertificate
    HostName:
      description: >-
        The hostname to which the connection was attempted. Should match the hostname of the server on which the health
        check implementation is running.
      type: string
      example: auth.open-finance-apihub.ae
    ConnectionEstablished:
      description: Indicator of whether a connection was established
      type: boolean