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