X-Road (NIIS) Diagnostics API

openapi: 3.2.0
info:
  title: X Road Global Diagnostics API
  version: 2.1.0
  contact:
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
    email: info@niis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged diagnostics across 2 of this provider''s published API definitions: security-server-admin-openapi.yaml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
  description: basepath for API v1
security:
- ApiKeyAuth: []
tags:
- name: Diagnostics
  description: diagnostics endpoints
paths:
  /diagnostics/info/download:
    get:
      tags:
      - Diagnostics
      summary: download diagnostics report
      operationId: downloadDiagnosticsReport
      description: Administrator downloads diagnostics report.
      responses:
        '200':
          description: system information
          content:
            application/json:
              schema:
                type: string
                format: binary
                description: system information file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/globalconf:
    get:
      tags:
      - Diagnostics
      summary: view global configuration diagnostics information
      operationId: getGlobalConfDiagnostics
      description: Administrator views the global configuration diagnostics information.
      responses:
        '200':
          description: global configuration diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalConfDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/ocsp-responders:
    get:
      tags:
      - Diagnostics
      summary: view ocsp responders diagnostics information
      operationId: getOcspRespondersDiagnostics
      description: Administrator views the ocsp responders diagnostics information.
      responses:
        '200':
          description: ocsp responders diagnostics information
          content:
            application/json:
              schema:
                type: array
                description: array of ocsp responder diagnostics objects
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/CaOcspDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/timestamping-services:
    get:
      tags:
      - Diagnostics
      summary: view timestamping services diagnostics information
      operationId: getTimestampingServicesDiagnostics
      description: Administrator views the timestamping services diagnostics information.
      responses:
        '200':
          description: timestamping services diagnostics information
          content:
            application/json:
              schema:
                type: array
                description: array of timestamping service diagnostics objects
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/TimestampingServiceDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/addon-status:
    get:
      tags:
      - Diagnostics
      summary: view addon services diagnostics information
      operationId: getAddOnDiagnostics
      description: Administrator views the proxy addon status diagnostics information.
      responses:
        '200':
          description: addon services diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOnStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/backup-encryption-status:
    get:
      tags:
      - Diagnostics
      summary: view backup encryption services diagnostics information
      operationId: getBackupEncryptionDiagnostics
      description: Administrator views the proxy backup encryption status diagnostics information.
      responses:
        '200':
          description: backup encryption services diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupEncryptionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/message-log-encryption-status:
    get:
      tags:
      - Diagnostics
      summary: view message log encryption and grouping services diagnostics information
      operationId: getMessageLogEncryptionDiagnostics
      description: Administrator views the proxy message log encryption and grouping diagnostics information.
      responses:
        '200':
          description: message log encryption and grouping diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLogEncryptionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/proxy-memory-usage-status:
    get:
      tags:
      - Diagnostics
      summary: view proxy memory usage information
      operationId: getProxyMemoryUsage
      description: Administrator views the proxy memory usage information.
      responses:
        '200':
          description: proxy memory usage information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyMemoryUsageStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/auth-cert-req-status:
    get:
      tags:
      - Diagnostics
      summary: view authentication certificate registration request status
      operationId: getAuthCertReqStatus
      description: Administrator views the authentication certificate registration request status.
      responses:
        '200':
          description: authentication certificate registration request status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/global-conf-status:
    get:
      tags:
      - Diagnostics
      summary: view global configuration download connection status
      operationId: getGlobalConfStatus
      description: Administrator views global configuration download connection status.
      responses:
        '200':
          description: global configuration download connection status
          content:
            application/json:
              schema:
                type: array
                description: array of statuses for the global configuration download connection
                items:
                  $ref: '#/components/schemas/GlobalConfConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/other-security-server-status:
    get:
      tags:
      - Diagnostics
      summary: view other security server connection status
      operationId: getOtherSecurityServerStatus
      description: Administrator views the other security server connection status.
      parameters:
      - in: query
        name: protocol_type
        description: service protocol type, must be REST or SOAP
        required: true
        schema:
          type: string
          enum:
          - REST
          - SOAP
          example: REST
      - in: query
        name: client_id
        description: clientId of the current security server. <instance_id>:<member_class>:<member_code>:<subsystem_code>. Subsystem code is optional.
        example: FI:GOV:123:Subsystem
        required: true
        schema:
          type: string
          format: text
      - in: query
        name: target_client_id
        description: targetClientId of the other security server. <instance_id>:<member_class>:<member_code>:<subsystem_code>.
        example: FI:GOV:123:Subsystem
        required: true
        schema:
          type: string
          format: text
      - in: query
        name: security_server_id
        description: securityServerId of the other security server. <instance_id>:<member_class>:<member_code>:<server_code>.
        example: FI:GOV:123:DEV
        required: true
        schema:
          type: string
          format: text
      responses:
        '200':
          description: other security server connection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /diagnostics/operational-monitoring:
    get:
      tags:
      - Diagnostics
      summary: view operational information
      operationId: getOperationalDataIntervals
      description: 'Administrator views the Security Server''s operational information on diagnostics page


        The request is rejected with status 400 and error code operational_data_intervals_out_of_range when


        the interval is less than 1 or more than 35791 minutes,


        records_to is before records_from, or


        the range divided into intervals would produce more than 100000 time buckets. The number of buckets is max(0, floor(to / interval) - floor(from / interval) + 2), where from and to are epoch milliseconds and interval is in milliseconds.'
      parameters:
      - in: query
        name: records_from
        description: the earliest time for the queried requests being made
        required: true
        schema:
          type: string
          format: date-time
          example: '2025-05-15T00:00:00.001Z'
      - in: query
        name: records_to
        description: the latest time for the queried requests being made
        required: true
        schema:
          type: string
          format: date-time
          example: '2025-05-15T00:00:00.001Z'
      - in: query
        name: interval
        description: interval in minutes the requests are divided into, from 1 to 35791. The range must produce at most 100000 time buckets.
        required: true
        schema:
          type: integer
          format: int32
          example: '15'
      - in: query
        name: security_server_type
        description: whether this Security Server was a 'Client' or a 'Producer'
        example: Client
        required: false
        schema:
          type: string
          format: text
      - in: query
        name: member_id
        description: clientId of the Member who made or received the request. <instance_id>:<member_class>:<member_code>:<subsystem_code>. Subsystem code is optional.
        example: FI:GOV:123:Subsystem
        required: false
        schema:
          type: string
          format: text
      - in: query
        name: service_id
        description: serviceId of the Service that received the request. <instance_id>:<member_class>:<member_code>:<subsystem_code>:<service_code>.<version_number>. Version number is optional.
        example: FI:GOV:123:Subsystem:MyService.V1
        required: false
        schema:
          type: string
          format: text
      responses:
        '200':
          description: operational information to be visualized
          content:
            application/json:
              schema:
                type: array
                description: array of operational info objects
                items:
                  $ref: '#/components/schemas/OperationalDataInterval'
        '400':
          description: interval, time range or number of time buckets is out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  schemas:
    GlobalConfConnectionStatus:
      type: object
      description: global configuration download connection status
      required:
      - download_url
      - connection_status
      properties:
        download_url:
          type: string
          format: text
          minLength: 1
          maxLength: 255
          description: download url of the global configuration
        connection_status:
          $ref: '#/components/schemas/ConnectionStatus'
    GlobalConfDiagnostics:
      type: object
      description: global configuration diagnostics
      required:
      - status_class
      - prev_update_at
      - next_update_at
      properties:
        status_class:
          readOnly: true
          description: diagnostics status class
          allOf:
          - $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        next_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        last_successful_url:
          type: string
          format: uri
          description: last successful configuration source URL
          example: https://example.org/configuration
          minLength: 1
          maxLength: 255
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    OperationalDataInterval:
      type: object
      description: Operational information to be visualized
      properties:
        interval_start_time:
          type: string
          format: date-time
          description: The beginning of this time window
        success_count:
          description: number of successful requests in this time window
          type: integer
          format: int64
        failure_count:
          description: number of failed requests in this time window
          type: integer
          format: int64
    ProxyMemoryUsageStatus:
      type: object
      description: proxy memory usage status
      required:
      - max_memory
      - total_memory
      - used_memory
      - usage_percent
      - is_used_over_threshold
      properties:
        max_memory:
          type: number
          readOnly: true
          description: Proxy's maximum memory
        total_memory:
          type: number
          readOnly: true
          description: Proxy's total allocated memory
        used_memory:
          type: number
          readOnly: true
          description: Proxy's used memory
        threshold:
          type: number
          readOnly: true
          description: Proxy memory usage alert threshold
        usage_percent:
          type: number
          readOnly: true
          description: Proxy's used memory percentage
        is_used_over_threshold:
          type: boolean
          readOnly: true
          description: Is usage over threshold
    MessageLogArchiveEncryptionMember:
      type: object
      description: message log archive encryption member
      required:
      - member_id
      properties:
        member_id:
          type: string
          readOnly: true
          description: member id
        keys:
          type: array
          uniqueItems: true
          description: array of keys
          items:
            type: string
            format: text
          readOnly: true
        default_key_used:
          type: boolean
          readOnly: true
          description: default key used
    MessageLogEncryptionStatus:
      type: object
      description: message log encryption statuses
      required:
      - message_log_archive_encryption_status
      - message_log_database_encryption_status
      - message_log_grouping_rule
      properties:
        message_log_archive_encryption_status:
          type: boolean
          readOnly: true
          description: message log archive encryption status
        message_log_database_encryption_status:
          type: boolean
          readOnly: true
          description: message log database encryption status
        message_log_grouping_rule:
          type: string
          readOnly: true
          description: message log grouping rule
        members:
          type: array
          description: message log encryption members
          items:
            $ref: '#/components/schemas/MessageLogArchiveEncryptionMember'
    BackupEncryptionStatus:
      type: object
      description: backup encryption statuses
      required:
      - backup_encryption_status
      properties:
        backup_encryption_status:
          type: boolean
          readOnly: true
          description: backup encryption status
        backup_encryption_keys:
          type: array
          description: backup encryption keys
          items:
            type: string
            format: text
            description: backup encryption key
    CodeWithDetails:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/CodeWithDetails
    OcspResponderDiagnostics:
      type: object
      description: OCSP responder diagnostics
      required:
      - url
      - status_class
      - next_update_at
      properties:
        url:
          type: string
          format: url
          description: url of the OCSP responder
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
        status_class:
          $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        next_update_at:
          type: string
          format: date-time
          description: next time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    DiagnosticStatusClass:
      type: string
      description: diagnostics status class
      example: OK
      enum:
      - OK
      - WAITING
      - FAIL
    AddOnStatus:
      type: object
      description: addon module statuses
      required:
      - messagelog_enabled
      - opmonitoring_enabled
      properties:
        messagelog_enabled:
          type: boolean
          readOnly: true
          description: MessageLog status
        opmonitoring_enabled:
          type: boolean
          readOnly: true
          description: OpMonitoring status
    TimestampingServiceDiagnostics:
      type: object
      description: timestamping service diagnostics
      required:
      - url
      - status_class
      - prev_update_at
      properties:
        url:
          type: string
          format: url
          description: url of the time stamping service
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
        status_class:
          $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    ConnectionStatus:
      type: object
      description: connection status
      required:
      - status_class
      - error
      properties:
        status_class:
          readOnly: true
          description: connection status class
          allOf:
          - $ref: '#/components/schemas/DiagnosticStatusClass'
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    CostType:
      description: cost type for services like TSP-s and OCSP responders
      enum:
      - FREE
      - PAID
      - UNDEFINED
      example: FREE
      type: string
    ErrorInfo:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    CaOcspDiagnostics:
      type: object
      description: Ocsp responder diagnostics
      required:
      - distinguished_name
      - ocsp_responders
      properties:
        distinguished_name:
          type: string
          format: text
          description: CA distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 255
          readOnly: true
        ocsp_responders:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/OcspResponderDiagnostics'
  examples:
    ErrorExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: X-Road-ApiKey token=<api key>
x-refined-from:
- security-server-admin-openapi.yaml
- x-road-global-security-server-admin-openapi.yml