Netcracker Database operation controller v3 API

openapi: 3.2.0
info:
  title: DBaaS Aggregator Database operation controller v3 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: Database operation controller v3
  description: This controller contains API for operations with already created databases, users.
paths:
  /api/v3/dbaas/namespaces/{namespace}/databases/link:
    post:
      summary: V3. Link databases for the requested microservices to target namespace
      description: Create additional classifiers for required databases in the target namespace, if there is no such classifiers.
      tags:
      - Database operation controller v3
      parameters:
      - description: Project namespace in which the databases are used
        required: true
        name: namespace
        in: path
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkDatabasesRequest'
        required: true
      responses:
        '200':
          description: All databases for requested microservices were linked to target namespace
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatabaseResponseV3ListCP'
        '400':
          description: Request does not pass validation. Maybe some required fields are empty
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Some error during databases linking
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Not Authorized
        '403':
          description: Not Allowed
      security:
      - SecurityScheme:
        - DBAAS_DB_EDITOR
  /api/v3/dbaas/namespaces/{namespace}/databases/recreate:
    post:
      summary: V3. Recreate database with existing classifier. Prohibited for Blue-Green
      description: Recreate existing database with same classifier in the same physicalDb or in another. The API can be useful if you want to migrate associated with microservice logical db to another physical database. So, DBaaS creates a new empty database. After it, you will get a new connection and can perform a migration.Pay attention, each request will produce a new database even if the database was previously recreated. So, if your response contains unsuccessful databases you must leave only these databases in the request. Otherwise successful databases will be recreated again. The previous database is not deleted but is marked as archived.
      tags:
      - Database operation controller v3
      parameters:
      - description: namespace where microservices live that associated with these databases
        required: true
        name: namespace
        in: path
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RecreateDatabaseRequest'
        required: true
      responses:
        '200':
          description: All requested databases were recreated. There are no unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecreateDatabaseResponse'
        '500':
          description: Some requested databases were not recreated. There are unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecreateDatabaseResponse'
        '400':
          description: Request does not pass validation. Maybe passed physical databases id is unregistered or logical database with requested classifier has not been created before.
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Not Authorized
        '403':
          description: Not Allowed
      security:
      - SecurityScheme:
        - DBAAS_DB_EDITOR
  /api/v3/dbaas/namespaces/{namespace}/databases/update-classifier/{type}:
    put:
      summary: V3. Update existing database classifier
      description: The API allows to update existing database classifier
      tags:
      - Database operation controller v3
      parameters:
      - description: Project namespace in which the databases are used
        required: true
        name: namespace
        in: path
        schema:
          type: string
      - description: Type of physical database where database was created, e.g. mongodb, postgresql
        required: true
        name: type
        in: path
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClassifierRequestV3'
        required: true
      responses:
        '400':
          description: '"from" or "to" classifiers must not be empty'
          content:
            application/json:
              schema:
                type: string
        '406':
          description: '"from" or "to" classifiers contain namespace different from in the path'
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Requested role is not allowed
          content:
            application/json:
              schema:
                type: string
        '409':
          description: 'There is a database with provided "to" classifier or '
          content:
            application/json:
              schema:
                type: string
        '404':
          description: There is no database with provided "from" classifier
          content:
            application/json:
              schema:
                type: string
        '200':
          description: The database classifier was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '403':
          description: Not Allowed
      security:
      - SecurityScheme:
        - DBAAS_DB_EDITOR
        - DB_CLIENT
  /api/v3/dbaas/namespaces/{namespace}/databases/update-connection/{type}:
    put:
      summary: V3. Update existing database connection properties
      description: The API allows to update existing database connection properties
      tags:
      - Database operation controller v3
      parameters:
      - description: Project namespace in which the databases are used
        required: true
        name: namespace
        in: path
        schema:
          type: string
      - description: Type of physical database where database was created, e.g. mongodb, postgresql
        required: true
        name: type
        in: path
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionPropertiesRequest'
        required: true
      responses:
        '400':
          description: Validation error
          content:
            application/json:
              examples:
                MissingClassifierOrProperties:
                  value: '"Database classifier or new connection properties must not be nil"'
                MissingRoleKey:
                  value: '"New connection properties must contain key ''role''"'
                EncryptedPasswordAsPlaintext:
                  value: '"Connection properties containing encryptedPassword must be stored in encrypted form, not as plaintext"'
                NamespaceMismatch:
                  value: '"The classifier contains a namespace that differs from the one in the path"'
              schema:
                type: string
        '404':
          description: Not found
          content:
            application/json:
              examples:
                NoSuchDatabase:
                  value: '"there is no existing database with such type and classifier"'
                NoConnectionPropertiesForRole:
                  value: '"Database with classifier does not contain connection properties for role"'
              schema:
                type: string
        '200':
          description: Database connection properties were updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '401':
          description: Not Authorized
        '403':
          description: Not Allowed
      security:
      - SecurityScheme:
        - DBAAS_DB_EDITOR
  /api/v3/dbaas/namespaces/{namespace}/password-changes:
    post:
      summary: V3. Change user password
      description: The API changes password of a user that is related to the specified database. A password will be changed to a random value.If classifier is not passed then all passwords of databases in the namespace and type will be changed.
      tags:
      - Database operation controller v3
      parameters:
      - description: Project namespace in which the databases are used
        name: namespace
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequestV3'
        required: true
      responses:
        '401':
          description: Requested role is not allowed
          content:
            application/json:
              schema:
                type: string
        '200':
          description: The passwords have been changed successfully. If errors will occur during the password changes, then the errors are aggregated and returned with maximum error status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordChangeResponse'
        '403':
          description: Not Allowed
        '400':
          description: Bad Request
      security:
      - SecurityScheme:
        - DB_CLIENT
components:
  schemas:
    UpdateConnectionPropertiesRequest:
      type: object
      required:
      - classifier
      - connectionProperties
      description: Contains classifier by which a database record for updating connection properties will be found and new connection properties
      properties:
        classifier:
          type: object
          additionalProperties: {}
          description: Database classifier.
        connectionProperties:
          type: object
          additionalProperties: {}
          description: New connection properties. Structure of connection properties for different db types may be found at https://perch.qubership.org/pages/viewpage.action?spaceKey=CLOUDCORE&title=DbaaS+Adapters
        physicalDatabaseId:
          type: string
          description: 'Specifies the new identification of physical database where a logical database is already located. You have to pass this parameter if your goal is to update and specify a new physical database.It is an optional parameter and if not specified then physical database will not change. FYI: You can get the list of all physical databases by "List registered physical databases" API.'
        resources:
          $ref: '#/components/schemas/DbResource'
          description: 'The list of the resources which related to the logical database, for example: user, database.You should pass this parameter if you change username or database name. In order to update the list you should get an original list, change one use and pass. FYI: You can get the list of origin database resources by "List of all databases" API with "withResources" query parameter.'
        dbName:
          type: string
          description: Name of database.
    PasswordChanged:
      type: object
      required:
      - classifier
      - connection
      properties:
        classifier:
          type: object
          additionalProperties: {}
          description: Database composite identify key.
        connection:
          type: object
          additionalProperties: {}
          description: New database connection.
    DatabaseStateStatus:
      type: string
      enum:
      - PROCESSING
      - CREATED
      - DELETING
      - DELETING_FAILED
      - ARCHIVED
      - ORPHAN
    NotRecreated:
      type: object
      required:
      - type
      - classifier
      - error
      properties:
        type:
          type: string
          description: Requested physical type of logical database. For example mongodb or postgresql
        classifier:
          type: object
          additionalProperties: {}
          description: Requested classifier
        error:
          type: string
          description: Contains a message of error that occurred during recreating
    RecreateDatabaseResponse:
      type: object
      description: Response model for recreate existing database API. The model contains successful and unsuccessful databases
      properties:
        successfully:
          type: array
          items:
            $ref: '#/components/schemas/Recreated'
          description: The list contains successfully recreated databases.
        unsuccessfully:
          type: array
          items:
            $ref: '#/components/schemas/NotRecreated'
          description: The list contains requests from which an error occurred during recreating. For these requests databases were not recreated.
    PasswordChangeRequestV3:
      type: object
      required:
      - type
      properties:
        classifier:
          type: object
          additionalProperties: {}
          description: Composite database identifier.
        type:
          type: string
          description: Database type.
        userRole:
          type: string
          description: Indicates which grants should have user in connection properties
    LinkDatabasesRequest:
      type: object
      required:
      - serviceNames
      - targetNamespace
      description: Request model for linking existing databases to different namespace
      properties:
        serviceNames:
          type: array
          items:
            type: string
          description: The list of microservice names whose databases will be linked to target namespace
        targetNamespace:
          type: string
          description: Namespace, to which databases will be linked
    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}'
    UpdateClassifierRequestV3:
      type: object
      required:
      - from
      - to
      description: Contains primary or source ("from") classifier by which a database record will be found and changed to target classifier ("from")
      properties:
        from:
          type: object
          additionalProperties: {}
          description: Primary or source classifier.
        to:
          type: object
          additionalProperties: {}
          description: Target classifier.
        fromV1orV2ToV3:
          type: boolean
          examples:
          - false
          description: Target classifier.
        clone:
          type: boolean
          examples:
          - false
          description: Create copy of record database in dbaas.
    Date:
      type: string
      format: date
      examples:
      - '2022-03-10'
    DbResource:
      type: object
      required:
      - kind
      - name
      properties:
        kind:
          type: string
          description: The kind of resource. For example database or user
        name:
          type: string
          description: Name of the resource.
    FieldTypeEnum:
      type: string
      enum:
      - PASSWORD
    ConnectionDescription:
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldDescription'
    DatabaseRegistry:
      type: object
      required:
      - classifier
      - namespace
      - type
      - database
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          description: A unique identifier of the document in the database. This field may not be used when searching by classifier for security purpose. In appears in response when Create database API is executed.
        timeDbCreation:
          $ref: '#/components/schemas/Date'
          type: string
          description: Time to create a database
        classifier:
          type: object
          additionalProperties: {}
          description: Classifier describes the purpose of the database and distinguishes this database from other database in the same namespase. It contains such keys as dbClassifier, scope, microserviceName, namespace. Setting keys depends on the database type.
        namespace:
          type: string
          description: Namespace where database is placed
        type:
          type: string
          description: Type of database, for example postgresql or mongodb
        database:
          $ref: '#/components/schemas/Database'
          description: It lists of database classifiers
        dbState:
          $ref: '#/components/schemas/DbState'
        databaseRegistry:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseRegistry'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/DbResource'
        oldClassifier:
          type: object
          additionalProperties: {}
        connectionProperties:
          type: array
          items:
            type: object
            additionalProperties: {}
        adapterId:
          type: string
        name:
          type: string
        markedForDrop:
          type: boolean
        backupDisabled:
          type: boolean
        dbOwnerRoles:
          type: array
          items:
            type: string
        settings:
          type: object
          additionalProperties: {}
        connectionDescription:
          $ref: '#/components/schemas/ConnectionDescription'
        warnings:
          type: array
          items:
            type: string
        externallyManageable:
          type: boolean
        bgVersion:
          type: string
        physicalDatabaseId:
          type: string
    PasswordChangeResponse:
      type: object
      properties:
        changed:
          type: array
          items:
            $ref: '#/components/schemas/PasswordChanged'
          description: List containing "classifier:connection" information with which the password was changed successfully.
        failed:
          type: array
          items:
            $ref: '#/components/schemas/PasswordFailed'
          description: List containing fail information.
    DatabaseResponse:
      type: object
      required:
      - classifier
      - connectionProperties
      - resources
      - namespace
      - type
      - adapterId
      - name
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          description: A unique identifier of the document in the database. This field might not be used when searching by classifier for security purpose. And it exists in the response when executing Create database API
        classifier:
          type: object
          additionalProperties: {}
          description: Classifier describes the purpose of the database and it distinguishes this database from other databases in the same namespace. It contains such keys as dbClassifier, isServiceDb, microserviceName, namespace. Setting keys depends on the database type.
        connectionProperties:
          type: object
          additionalProperties: {}
          description: This is an information about connection to database. It contains such keys as url, authDbName, username, password, port, host.Setting keys depends on the database type.
        resources:
          $ref: '#/components/schemas/DbResource'
          description: It lists the resources which will be deleted when sending the request to delete the database.
        namespace:
          type: string
          description: Namespace where database is placed.
        type:
          type: string
          description: Type of database, for example postgresql or mongodb
        adapterId:
          type: string
          description: This field indicates for which adapter the database was created.
        name:
          type: string
          description: Name of database. It may be generated or, if name was specified in the request, then it will be specified.
        markedForDrop:
          type: boolean
          description: A marker indicating if the database will be deleted.
        timeDbCreation:
          $ref: '#/components/schemas/Date'
          type: string
          description: Time to create a database.
        backupDisabled:
          type: boolean
        settings:
          type: object
          additionalProperties: {}
          description: Additional settings for creating a database.
        connectionDescription:
          $ref: '#/components/schemas/ConnectionDescription'
          type: object
          description: This parameter describes a connection properties.
        warnings:
          type: array
          items:
            type: string
          description: List of warning messages.
        externallyManageable:
          type: boolean
          description: This parameter specifies if a control over the database is not carried out by the DBaaS adapter
        dbOwnerRoles:
          type: array
          items:
            type: string
          description: The list of roles which are related to this logical database. The external security service (e.g. DBaaA Agent) can perform a verification process on this field.
        classifierV3Migrated:
          type: boolean
          description: Indicate that classifier migrated correctly to V3 structure
    DbState:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        state:
          $ref: '#/components/schemas/DatabaseStateStatus'
          type: string
          deprecated: true
        databaseState:
          $ref: '#/components/schemas/DatabaseStateStatus'
        description:
          type: string
        podName:
          type: string
    DatabaseResponseV3ListCP:
      type: object
      required:
      - classifier
      - namespace
      - type
      - name
      - connectionProperties
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          description: A unique identifier of the document in the database. This field might not be used when searching by classifier for security purpose. And it exists in the response when executing Create database API
        classifier:
          type: object
          additionalProperties: {}
          description: Classifier describes the purpose of the database and it distinguishes this database from other databases in the same namespace. It contains such keys as dbClassifier, isServiceDb, microserviceName, namespace. Setting keys depends on the database type.
        namespace:
          type: string
          description: Namespace where database is placed.
        type:
          type: string
          description: Type of database, for example PostgreSQL or MongoDB
        name:
          type: string
          description: Name of database. It may be generated or, if name was specified in the request, then it will be specified.
        externallyManageable:
          type: boolean
          description: This parameter specifies if a control over the database is not carried out by the DBaaS adapter
        timeDbCreation:
          $ref: '#/components/schemas/Date'
          type: string
          description: Time to create a database.
        settings:
          type: object
          additionalProperties: {}
          description: Additional settings for creating a database.
        backupDisabled:
          type: boolean
          description: 'This field indicates if backup is disabled or not. If true, database would not be backed up. Example: false'
        physicalDatabaseId:
          type: string
          description: Physical database identifier where the registered database should be located. If it is absent, adapter id may be used to identify the target physical database.
        connectionProperties:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: This is an information about connection to database. It contains such keys as url, authDbName, username, password, port, host.Setting keys depends on the database type.
        resources:
          $ref: '#/components/schemas/DbResource'
          description: list of resources is necessary for bulk drop resources operation. Specified if you add query parameter "withResources" = true to request
    RecreateDatabaseRequest:
      type: object
      required:
      - type
      - classifier
      - physicalDatabaseId
      description: Request model for recreate existing database. The database will have the same settings and classifier as original
      properties:
        type:
          type: string
          description: The physical type of logical database. For example mongodb or postgresql
        classifier:
          type: object
          additionalProperties: {}
          description: The unique key of existing database. The list of all created databases in a specific namespace can be found by by 'List of all databases' API.
        physicalDatabaseId:
          type: string
          description: Specifies the identificator of physical database where a logical database will be recreated. You can get the list of all physical databases by "List registered physical databases" API.
    Database:
      type: object
      required:
      - oldClassifier
      - classifier
      - connectionProperties
      - namespace
      - type
      - adapterId
      - name
      - resources
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          type: string
          description: A unique identifier of the document in the database. This field may not be used when searching by classifier for security purpose. In appears in response when Create database API is executed.
        oldClassifier:
          type: object
          additionalProperties: {}
          description: Old classifier describes the purpose of the database and distinguishes this database from other database in the same namespase. It contains such keys as dbClassifier, isService, microserviceName, namespace. Setting keys depends on the database type.
        classifier:
          type: object
          deprecated: true
          additionalProperties: {}
          description: Classifier describes the purpose of the database and distinguishes this database from other database in the same namespase. It contains such keys as dbClassifier, scope, microserviceName, namespace. Setting keys depends on the database type.
        connectionProperties:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: The information about connection to database. It contains such keys as url, authDbName, username, password, port, host.Setting keys depends on the database type.
        namespace:
          type: string
          deprecated: true
          description: Namespace where database is placed
        type:
          type: string
          deprecated: true
          description: Type of database, for example postgresql or mongodb
        adapterId:
          type: string
          description: This field indicates for which adapter the database was created.
        name:
          type: string
          description: Name of database. It may be generated or, if name was specified in a request then it will be specified.
        markedForDrop:
          type: boolean
          description: A marker indicating that the database will be deleted.
        timeDbCreation:
          $ref: '#/components/schemas/Date'
          type: string
          description: Time to create a database
        backupDisabled:
          type: boolean
          description: 'This field indicates if backup is disabled or not. If true, database would not be backed up. Example: false'
        dbOwnerRoles:
          type: array
          items:
            type: string
          description: The list of roles which are related to this logical database. The external security service (e.g. DBaaS Agent) can perform a verification process on this field.
        settings:
          type: object
          additionalProperties: {}
          description: Additional settings for creating a database
        connectionDescription:
          $ref: '#/components/schemas/ConnectionDescription'
          type: object
          description: This parameter describes connection properties.
        warnings:
          type: array
          items:
            type: string
          description: Lists warning messages
        externallyManageable:
          type: boolean
          description: This parameter specifies if a control over the database is not carried out by the DBaaS adapter.
        bgVersion:
          type: string
          description: Database version. It uses for blue-green
        physicalDatabaseId:
          type: string
        databaseRegistry:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseRegistry'
        resources:
          $ref: '#/components/schemas/DbResource'
          description: It lists resource which will be deleted when sending the request for delete a database
        dbState:
          $ref: '#/components/schemas/DbState'
    FieldDescription:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FieldTypeEnum'
    PasswordFailed:
      type: object
      required:
      - classifier
      - message
      properties:
        classifier:
          type: object
          additionalProperties: {}
          description: Database composite identify key.
        message:
          type: string
          description: Error message.
    Recreated:
      type: object
      required:
      - classifier
      - type
      - newDb
      properties:
        classifier:
          type: object
          additionalProperties: {}
          description: Requested classifier
        type:
          type: string
          description: Requested physical type of logical database. For example mongodb or postgresql
        newDb:
          $ref: '#/components/schemas/DatabaseResponse'
          type: object
          description: A recreated logical database. This database has the same classifier as a original but connection properties are different (url, dbname, username, password)
  securitySchemes:
    SecurityScheme:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Authentication