X-Road (NIIS) Backups API

openapi: 3.2.0
info:
  title: X Road Global Backups API
  contact:
    email: info@niis.org
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
  description: 'Operations tagged backups across 4 of this provider''s published API definitions: central-server-admin-openapi.yaml, security-server-admin-openapi.yaml, x-road-global-central-server-admin-openapi.yml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: basepath for API v1
  url: /api/v1
security:
- ApiKeyAuth: []
tags:
- name: Backups
  description: resources related to Backups and Backup Restoration
paths:
  /backups:
    get:
      description: Administrator views the backups for the central server.
      operationId: getBackups
      responses:
        '200':
          content:
            application/json:
              schema:
                description: array of backup objects sorted newest to oldest
                items:
                  $ref: '#/components/schemas/Backup'
                type: array
                uniqueItems: false
          description: list of central server backups
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: get central server backups
      tags:
      - Backups
    post:
      description: 'Generates a new central server backup.


        This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup generation script.'
      operationId: addBackup
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
          description: item created
        '202':
          description: item accepted
        '400':
          content:
            application/json:
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                error_response:
                  $ref: '#/components/examples/ErrorExample'
              schema:
                $ref: '#/components/schemas/ErrorInfo'
          description: request was invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: add new backup for the central server
      tags:
      - Backups
    servers:
    - description: basepath for API v1
      url: /api/v1
  /backups/upload:
    post:
      description: 'Uploads new central server backup to the system.


        Note that it is possible to overwrite an existing backup file with the same name.


        Attempt to upload a new backup file having the same name with an existing backup and with query parameter ignore_warnings = false causes the operation to fail with a warning in response''s ErrorInfo object.


        Attempt to upload a new backup file having the same name with an existing backup and with query parameter ignore_warnings = true will overwrite the existing backup.


        The warning response has a warning code warning_file_already_exists and the metadata field contains the name of the existing backup'
      operationId: uploadBackup
      parameters:
      - description: If true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail.
        in: query
        name: ignore_warnings
        required: false
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BackupArchive'
        description: backup to add
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
          description: item created
        '202':
          description: item accepted
        '400':
          content:
            application/json:
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                warnings_response:
                  $ref: '#/components/examples/UploadExistingBackupWarningExample'
              schema:
                $ref: '#/components/schemas/ErrorInfo'
          description: request was invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: upload new backup for the central server
      tags:
      - Backups
    servers:
    - description: basepath for API v1
      url: /api/v1
  /backups/{filename}:
    delete:
      description: Administrator deletes the backup of the central server.
      operationId: deleteBackup
      parameters:
      - $ref: '#/components/parameters/FilenameParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: delete central server backup
      tags:
      - Backups
    servers:
    - description: basepath for API v1
      url: /api/v1
  /backups/{filename}/download:
    get:
      description: Administrator downloads the backup of the central server.
      operationId: downloadBackup
      parameters:
      - $ref: '#/components/parameters/FilenameParam'
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                description: backup file
                format: binary
                type: string
          description: backup file downloaded
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: download central server backup
      tags:
      - Backups
    servers:
    - description: basepath for API v1
      url: /api/v1
  /backups/{filename}/restore:
    put:
      description: 'Administrator restores the central server configuration from backup.


        This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup restore script.'
      operationId: restoreBackup
      parameters:
      - $ref: '#/components/parameters/FilenameParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRestorationStatus'
          description: restore was successful
        '400':
          content:
            application/json:
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                error_response:
                  $ref: '#/components/examples/ErrorExample'
              schema:
                $ref: '#/components/schemas/ErrorInfo'
          description: request was invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: restore central server configuration from backup
      tags:
      - Backups
    servers:
    - description: basepath for API v1
      url: /api/v1
  /backups/ext:
    post:
      tags:
      - Backups
      summary: add new backup for the security server and return extra backup state
      operationId: addBackupExt
      description: 'Adds security server backup to the system.


        This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup generation script.'
      responses:
        '201':
          description: item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupExt'
        '202':
          description: item accepted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo_2'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample_2'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample_2'
        '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
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  responses:
    NotFound:
      description: resource requested does not exists
    NoContent:
      description: request was successful
    Unauthorized:
      description: authentication credentials are missing
    Forbidden:
      description: request has been refused
    BadRequest:
      description: request was invalid
    Conflict:
      description: an existing item already exists
    InternalServerError:
      description: internal server error
  schemas:
    BackupRestorationStatus:
      description: response that tells if hsm tokens were logged out during the restore process
      properties:
        hsm_tokens_logged_out:
          default: false
          description: whether any hsm tokens were logged out during the restore process
          type: boolean
      type: object
    Backup:
      description: central server backup
      properties:
        filename:
          description: backup filename
          example: configuration_backup_20181224.tar
          format: filename
          maxLength: 255
          minLength: 1
          type: string
        compatible:
          type: boolean
          description: whether this backup is compatible with this server's backup format
      required:
      - filename
      - compatible
      type: object
    ErrorInfo:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    BackupArchive:
      description: central server backup archive file
      properties:
        backup:
          format: binary
          type: string
      type: object
    TokensLoggedOut:
      description: response that tells if hsm tokens were logged out during the restore process
      type: object
      properties:
        hsm_tokens_logged_out:
          description: whether any hsm tokens were logged out during the restore process
          type: boolean
          default: false
    BackupExt:
      allOf:
      - $ref: '#/components/schemas/Backup_2'
      type: object
      description: security server backup with extra information
      required:
      - local_conf_present
      properties:
        local_conf_present:
          type: boolean
          description: if local configuration is present in the backup
    Backup_2:
      type: object
      description: security server backup
      required:
      - filename
      - created_at
      - compatible
      properties:
        filename:
          type: string
          format: filename
          description: backup filename
          example: configuration_backup_20181224.tar
          minLength: 1
          maxLength: 255
        created_at:
          type: string
          format: date-time
          description: backup created at
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        compatible:
          type: boolean
          description: whether this backup is compatible with this server's backup format
    ErrorInfo_2:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    BackupArchive_2:
      type: object
      description: security server backup archive file
      properties:
        backup:
          type: string
          format: binary
          description: backup archive file
    BackupExt_2:
      allOf:
      - $ref: '#/components/schemas/Backup_3'
      type: object
      description: security server backup with extra information
      required:
      - local_conf_present
      properties:
        local_conf_present:
          type: boolean
          description: if local configuration is present in the backup
    Backup_3:
      type: object
      description: security server backup
      required:
      - filename
      - created_at
      - compatible
      properties:
        filename:
          type: string
          format: filename
          description: backup filename
          example: configuration_backup_20181224.tar
          minLength: 1
          maxLength: 255
        created_at:
          type: string
          format: date-time
          description: backup created at
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        compatible:
          type: boolean
          description: whether this backup is compatible with this server's backup format
    ErrorInfo_3:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    BackupArchive_3:
      type: object
      description: security server backup archive file
      properties:
        backup:
          type: string
          format: binary
          description: backup archive file
  examples:
    ErrorExample:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    UploadExistingBackupWarningExample:
      summary: Warning response when uploading a new backup configuration file with an existing name
      value:
        error:
          code: warnings_detected
        status: 400
        warnings:
        - code: warning_file_already_exists
          metadata:
          - conf_backup_20201006-094932.tar
    ErrorWithMetadataExample:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
    ErrorExample_2:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    ErrorWithMetadataExample_2:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
    ErrorExample_3:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    ErrorWithMetadataExample_3:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
  parameters:
    FilenameParam:
      in: path
      name: filename
      description: filename of the backup
      required: true
      schema:
        format: filename
        maxLength: 255
        minLength: 1
        type: string
  securitySchemes:
    ApiKeyAuth:
      description: X-Road-ApiKey token=<api key>
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- central-server-admin-openapi.yaml
- security-server-admin-openapi.yaml
- x-road-global-central-server-admin-openapi.yml
- x-road-global-security-server-admin-openapi.yml