Netcracker Backup & Restore API

openapi: 3.2.0
info:
  title: DBaaS Aggregator Backup & Restore API
  version: 6.13.2
  description: This documentation presents the REST API for the "Database as a Service" (DBaaS) component. DBaaS acts as an aggregator for all adapters. It is designed to collect requests for managed databases and route them to the appropriate adapter. DBaaS stores information about all databases used in a cloud project. These databases are isolated by namespace. DBaaS uses a Classifier to identify databases within a cloud namespace. The Classifier includes service-related information such as scope, microservice name, tenant ID, and namespace.
tags:
- name: Backup & Restore
  description: Backup & Restore operations for DBaaS
paths:
  /api/backups/v1/backup:
    post:
      summary: Initiate database backup
      description: Starts an asynchronous backup operation for the specified databases. Returns immediately with a backup name that can be used to track progress.
      tags:
      - Backup & Restore
      parameters:
      - name: dryRun
        in: query
        schema:
          type: boolean
          default: false
      requestBody:
        description: Backup request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupRequest'
        required: true
      responses:
        '200':
          description: Backup operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupResponse'
        '202':
          description: Backup operation initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '409':
          description: The request could not be completed due to a conflict with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/backup/{backupName}:
    get:
      summary: Get backup details
      description: Retrieve details about a specific backup operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the backup
        required: true
        name: backupName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '200':
          description: Backup details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
    delete:
      summary: Delete backup
      description: Delete the backup operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the backup
        required: true
        name: backupName
        in: path
        schema:
          type: string
          pattern: \S
      - name: force
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '202':
          description: Backup delete initialized successfully
        '204':
          description: Backup deleted successfully
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/backup/{backupName}/metadata:
    get:
      summary: Get backup metadata
      description: Retrieve metadata about a completed backup
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the backup
        required: true
        name: backupName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '200':
          description: Backup metadata retrieved successfully
          headers:
            Digest:
              description: Digest header with SHA-256 checksum of the response body
              schema:
                type: string
                examples:
                - SHA-256=abc123...
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/backup/{backupName}/restore:
    post:
      summary: Restore from backup
      description: Initiate a database restore operation from an existing backup.This operation is asynchronous and returns immediately with a restore name that can be used to track progress.Operation is not idempotent
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the backup
        required: true
        name: backupName
        in: path
        schema:
          type: string
          pattern: \S
      - name: dryRun
        in: query
        schema:
          type: boolean
          default: false
      requestBody:
        description: Restore request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreRequest'
        required: true
      responses:
        '202':
          description: Restore operation initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '409':
          description: The request could not be completed due to a conflict with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/backup/{backupName}/status:
    get:
      summary: Get backup status
      description: Retrieve the current status of a backup operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the backup
        required: true
        name: backupName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '200':
          description: Backup status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupStatusResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/operation/uploadMetadata:
    post:
      summary: Upload backup metadata
      description: Upload backup metadata
      tags:
      - Backup & Restore
      parameters:
      - description: 'Digest header in format: SHA-256=<base64-hash>'
        in: header
        name: Digest
        required: true
        schema:
          type: string
          examples:
          - SHA-256=nOJRJg...
      requestBody:
        description: Backup metadata
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupResponse'
        required: true
      responses:
        '200':
          description: Backup metadata uploaded successfully
          content:
            application/json:
              schema: {}
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '409':
          description: The request could not be completed due to a conflict with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/restore/{restoreName}:
    get:
      summary: Get restore details
      description: Retrieve details about a specific restore operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the restore operation
        required: true
        name: restoreName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '200':
          description: Restore details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreResponse'
        '400':
          description: The request was invalid or cannot be served
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
    delete:
      summary: Delete restore
      description: Delete a restore operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the restore operation
        required: true
        name: restoreName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '204':
          description: Restore operation deleted successfully
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/restore/{restoreName}/retry:
    post:
      summary: Retry restore
      description: Retry a failed restore operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the restore operation
        required: true
        name: restoreName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '202':
          description: Restore retry accepted and is being processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '409':
          description: The request could not be completed due to a conflict with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '422':
          description: The request was accepted, but the server couldn't process due to incompatible resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
  /api/backups/v1/restore/{restoreName}/status:
    get:
      summary: Get restore status
      description: Retrieve the current status of a restore operation
      tags:
      - Backup & Restore
      parameters:
      - description: Unique name of the restore operation
        required: true
        name: restoreName
        in: path
        schema:
          type: string
          pattern: \S
      responses:
        '200':
          description: Restore status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreStatusResponse'
        '401':
          description: Authentication is required and has failed or has not been provided
        '403':
          description: The request was valid, but the server is refusing action
        '404':
          description: The requested resource could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmfErrorResponse'
      security:
      - SecurityScheme:
        - BACKUP_MANAGER
components:
  schemas:
    RestoreStatusResponse:
      type: object
      required:
      - status
      description: Current status of a restore operation
      properties:
        status:
          type:
          - string
          - object
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          - DELETED
          description: Current state of the restore operation
        total:
          type: integer
          format: int32
          examples:
          - 5
          description: Total number of databases to be restored
          minimum: 0
        completed:
          type: integer
          format: int32
          examples:
          - 3
          description: Number of databases successfully restored
          minimum: 0
        errorMessage:
          type: string
          examples:
          - Insufficient permissions to create database
          description: Error details if the restore failed
    BackupStatusResponse:
      type: object
      required:
      - status
      description: Current status of a backup operation
      properties:
        status:
          type:
          - string
          - object
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          - DELETE_IN_PROGRESS
          - DELETED
          description: Current state of the backup operation
        total:
          type: integer
          format: int32
          examples:
          - 5
          description: Total number of databases being backed up
        completed:
          type: integer
          format: int32
          examples:
          - 3
          description: Number of databases successfully backed up
        size:
          type: integer
          format: int64
          examples:
          - 1073741824
          description: Total size of the backup in bytes
        errorMessage:
          type: string
          examples:
          - Failed to connect to database
          description: Error details if the backup failed
    TmfError:
      type: object
      properties:
        id:
          type: string
        referenceError:
          type: string
        code:
          type: string
        reason:
          type: string
        message:
          type: string
        status:
          type: string
        source: {}
        meta:
          type: object
          additionalProperties: {}
    BackupExternalDatabaseResponse:
      type: object
      required:
      - id
      - name
      description: External database details
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          examples:
          - 550e8400-e29b-41d4-a716-446655440000
          description: Identifier of the external backup database
        name:
          type: string
          examples:
          - mydb
          description: Name of the external database
        type:
          type: string
          examples:
          - postgresql
          description: Type of the database
        classifiers:
          type: array
          examples:
          - - namespace: namespace
              microserviceName: microserviceName
              scope: service
          items:
            type: object
            additionalProperties: {}
          description: List of database classifiers. Each classifier is a sorted map of attributes.
    Filter:
      type: object
      description: Single filter criteria for backup and restore operations
      properties:
        namespace:
          type: array
          items:
            type: string
          description: Filter by Kubernetes namespaces
        microserviceName:
          type: array
          items:
            type: string
          description: Filter by microservice names
        databaseType:
          type: array
          items:
            type: string
          description: Filter by database types
        databaseKind:
          type: array
          items:
            type: string
            enum:
            - CONFIGURATION
            - TRANSACTIONAL
          description: Filter by database kinds
    RestoreResponse:
      type: object
      required:
      - restoreName
      - backupName
      - storageName
      - externalDatabaseStrategy
      - status
      - total
      - completed
      description: Response containing the restore operation details
      properties:
        restoreName:
          type: string
          examples:
          - restore-before-prod-update-20251203T1020-4t6S
          pattern: \S
          description: Unique name of the restore
        backupName:
          type: string
          examples:
          - before-prod-update-20251013T1345-G5s8
          pattern: \S
          description: Unique name of the backup
        storageName:
          type: string
          examples:
          - s3-backend
          pattern: \S
          description: Name of the storage backend containing the restore
        blobPath:
          type: string
          examples:
          - /backups
          description: Path to the restore file in the storage
        externalDatabaseStrategy:
          type:
          - string
          - object
          enum:
          - FAIL
          - SKIP
          - INCLUDE
          examples:
          - FAIL
          description: How to handle external databases during restore
        filterCriteria:
          type: object
          description: Criteria used to filter restore operations
          properties:
            include:
              type: array
              items:
                $ref: '#/components/schemas/Filter'
              description: Include databases that match any of the filters in the list
            exclude:
              type: array
              items:
                $ref: '#/components/schemas/Filter'
              description: Exclude databases that match any of the filters in the list
        mapping:
          type: object
          description: Mapping configuration for the restore
          properties:
            namespaces:
              type: object
              examples:
              - source-namespace: target-namespace
              additionalProperties:
                type: string
              description: Mapping of source namespace to target namespace
            tenants:
              type: object
              examples:
              - source-tenant: target-tenant
              additionalProperties:
                type: string
              description: Mapping of source tenant to target tenant
        status:
          type:
          - string
          - object
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          - DELETED
          description: Current state of the restore operation
        total:
          type: integer
          format: int32
          examples:
          - 5
          description: Total number of databases being restored
        completed:
          type: integer
          format: int32
          examples:
          - 5
          description: Completed databases restore operation
        errorMessage:
          type: string
          examples:
          - Backup Not Found
          description: Aggregated error messages during restore operation
        logicalRestores:
          type: array
          items:
            $ref: '#/components/schemas/LogicalRestoreResponse'
          description: List of logical restores
        externalDatabases:
          type: array
          items:
            $ref: '#/components/schemas/RestoreExternalDatabaseResponse'
          description: List of external databases
    TmfErrorResponse:
      type: object
      properties:
        id:
          type: string
        referenceError:
          type: string
        code:
          type: string
        reason:
          type: string
        message:
          type: string
        status:
          type: string
        source: {}
        meta:
          type: object
          additionalProperties: {}
        errors:
          type: array
          items:
            $ref: '#/components/schemas/TmfError'
        '@type':
          type: string
        '@schemaLocation':
          type: string
    BackupDatabaseResponse:
      type: object
      required:
      - id
      - name
      - status
      - path
      description: Logical database backup details
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          examples:
          - 550e8400-e29b-41d4-a716-446655440000
          description: Identifier of the backup database
        name:
          type: string
          examples:
          - mydb
          description: Name of the database
        classifiers:
          type: array
          examples:
          - - namespace: namespace
              microserviceName: microserviceName
              scope: service
          items:
            type: object
            additionalProperties: {}
          description: List of database classifiers. Each classifier is a sorted map of attributes.
        settings:
          type: object
          examples:
          - key: value
          additionalProperties: {}
          description: Database settings as a key-value map
        users:
          type: array
          examples:
          - - name: username
              role: admin
          items:
            $ref: '#/components/schemas/User'
          description: List of database users
        configurational:
          type: boolean
          examples:
          - true
          description: Indicates the type of the database
        status:
          type:
          - string
          - object
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - FAILED
          - RETRYABLE_FAIL
          - COMPLETED
          description: Current state of the backup database
        size:
          type: integer
          format: int64
          examples:
          - 12256
          description: Size of the backup
        duration:
          type: integer
          format: int64
          examples:
          - 12000
          description: Duration of the backup operation
        path:
          type: string
          examples:
          - /backups/mydb-2025-11-13.bak
          description: Path to the backup file in the storage
        errorMessage:
          type: string
          examples:
          - Backup Not Found
          description: Error message if the backup failed
        creationTime:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2025-11-13T12:34:56Z'
          description: Timestamp when the backup was created
    UUID:
      type: string
      format: uuid
      pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'
    User:
      type: object
      description: Database user information
      properties:
        name:
          type: string
          examples:
          - username
          description: Name of the database user
        role:
          type: string
          examples:
          - admin
          description: Role of the database user
    LogicalBackupResponse:
      type: object
      required:
      - id
      - logicalBackupName
      - adapterId
      - type
      - status
      - backupDatabases
      description: Logical backup details
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          examples:
          - 550e8400-e29b-41d4-a716-446655440000
          description: Identifier of the logical backup
        logicalBackupName:
          type: string
          description: Name of the logical backup in adapter
        adapterId:
          type: string
          examples:
          - 4e1e9922-e5bf-490d-bb57-18a14de593c6
          description: Unique identifier of the adapter
        type:
          type: string
          description: Type of the adapter
        status:
          type:
          - string
          - object
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - FAILED
          - RETRYABLE_FAIL
          - COMPLETED
          description: Current state of the backup databases of one adapter
        errorMessage:
          type: string
          examples:
          - Backup Not Found
          description: Error message if backup failed
        creationTime:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2025-11-13T12:34:56Z'
          description: Timestamp when the backup was created
        completionTime:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2025-11-13T12:45:00Z'
          description: Timestamp when the backup completed
        back

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netcracker/refs/heads/main/openapi/netcracker-backup-restore-api-openapi.yml