Introduction

Hyper Protect DBaaS is the next evolution level on how data is stored in a highly secured enterprise cloud service ideally suited for workloads with sensitive data. It allows you to retain your data in a fully encrypted client database without need for specialized skills. This service provides capabilities to provision, manage, maintain and monitor multiple database types like MongoDB through standardized APIs. Hyper Protect DBaaS protects against threats of data breach and data manipulation leveraging the strengths of LinuxONE pervasive encryption, scalability, performance and IBM Secure Service Container technology.

The IBM Cloud™ Hyper Protect DBaaS API is a REST-based API for reading and writing objects.

For details about using IBM Cloud™ Hyper Protect DBaaS, see the IBM Cloud docs.

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token and user id in API requests.

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token and IBM Cloud user id. For more information, see Retrieving an access token and user id programmatically.

Error handling

The IBM Cloud Hyper Protect DBaaS service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Methods

Get an access token from IBM Cloud API Key.

GET /auth/token
Request

Custom Headers

  • The IBM Cloud API Key.

Response

The access token of one user.

Status Code

  • The request was successful.

  • The API Key is needed as a parameter.

  • Internal error.

Example responses

Show the detail information of the specific cluster.

GET /clusters/{cluster_id}
Request

Path Parameters

  • The UUID of a cluster object.

Response

An object which shows detail information of a cluster which has id, name, state, three replicas and so on.

Status Code

  • The request was successful.

  • Parameter error.

  • Cluster unavailable.

  • Internal error.

Example responses

Get information about all the users in the specified database cluster.

GET /clusters/{cluster_id}/users
Request

Path Parameters

  • The UUID of a cluster object.

Response

Object of information of users.

Status Code

  • The request was successful.

  • Cluster unavailable.

  • Internal error.

Example responses

Create a user in a database cluster.

POST /clusters/{cluster_id}/users
Request

Path Parameters

  • The UUID of a cluster object.

Information of the user you want to create.

Response

OK message object.

Status Code

  • The request was successful.

  • Parameter error.

  • Clusters unavailable.

  • Internal error.

Example responses

Delete a user from a database cluster.

DELETE /clusters/{cluster_id}/users/{db_user_id}
Request

Path Parameters

  • The UUID of a cluster object.

  • The ID of the user you want to delete. For MongoDB, it should be "authentication_database.username"; for example: "mydb.syrena".

Response

OK message object.

Status Code

  • The request was successful.

  • Cluster unavailable. Or the user id is not found.

  • Internal error.

Example responses

Get a user's information from a database cluster.

GET /clusters/{cluster_id}/users/{db_user_id}
Request

Path Parameters

  • The UUID of a cluster object.

  • The ID of the user about which you want to get information. For MongoDB, it should be "authentication_database.username"; for example: "mydb.syrena".

Response

A user information object received.

Status Code

  • The request was successful.

  • Cluster unavailable. Or the user id is not found.

  • Internal error.

Example responses

Get a list of all databases in database cluster.

GET /clusters/{cluster_id}/databases
Request

Path Parameters

  • The UUID of a cluster object.

Response

All databases information of a cluster.

Status Code

  • The request was successful.

  • Cluster unavailable.

  • Internal error.

Example responses

Create a database in database cluster.

POST /clusters/{cluster_id}/databases
Request

Path Parameters

  • The UUID of a cluster object.

Information of the database you want to create.

Example:
Response

OK message object.

Status Code

  • The request was successful.

  • Parameter error.

  • Cluster unavailable.

  • Internal error.

Example responses

Delete a database from a database cluster.

DELETE /clusters/{cluster_id}/databases/{name}
Request

Path Parameters

  • The UUID of a cluster object.

  • The name of the database you want to delete.

Response

OK message object.

Status Code

  • The request was successful.

  • Cluster unavailable, or the database is not found.

  • Internal error.

Example responses

Stop a database service instance.

POST /instances/{instance_id}/stop
Request

Path Parameters

  • The UUID of an instance object.

Force the database instance to stop.

Response

OK message object.

Status Code

  • The request was successful.

  • Wrong parameter type; this is usually caused by passing a non-boolean value as the force parameter.

  • Required resource does not exist; this is usually caused by passing an invalid instance ID.

  • Internal error.

Example responses

Start a database service instance.

POST /instances/{instance_id}/start
Request

Path Parameters

  • The UUID of an instance object.

Response

OK message object.

Status Code

  • The request was successful.

  • Required resource does not exist; this is usually caused by passing an invalid instance ID.

  • Internal error.

Example responses

Restart a database service instance.

POST /instances/{instance_id}/restart
Request

Path Parameters

  • The UUID of an instance object.

Force the database instance to restart.

Response

OK message object.

Status Code

  • The request was successful.

  • Wrong parameter type; this is usually caused by passing a non-boolean value as the force parameter.

  • Required resource does not exist; this is usually caused by passing an invalid instance ID.

  • Internal error.

Example responses

Get a list of current logs.

GET /instances/{instance_id}/logs
Request

Path Parameters

  • The UUID of an instance object.

Response

Logs object.

Status Code

  • The request was successful.

  • Required resource does not exist; this is usually caused by passing an invalid instance ID.

  • Internal error.

Example responses

Get the content of the specified log file.

GET /instances/{instance_id}/logs/{log_name}
Request

Custom Headers

  • Allowable values: [application/json,application/x-download]

Path Parameters

  • The UUID of an instance object.

  • The name of the log file.

Response

File downloaded.

Status Code

  • The request was successful. A log file stream will be returned.

  • Required resource does not exist; this is usually caused by passing an invalid instance ID.

  • Internal error.

No Sample Response

This method does not specify any sample responses.

Query one or more IBM Cloud service instance of Hyperprotect DBaaS on the server indicated by the URL.

GET /services
Request

Custom Headers

  • Valid IAM access token

Query Parameters

  • The name of service instance to be queried. Note that the IBM Cloud allows multiple service instances share one name, the name query may return multiple service instances. If neither a "name" nor a "guid" is given, all Hyperprotect DBaaS instances have been created on the server will be returned.

  • The guid ("cluster_id" in DBaaS term) of the service instance to be queried. The guid always indicates one service instance. If neither a "name" nor a "guid" is given, all Hyperprotect DBaaS instances have been created on the server will be returned.

Response

Objects about all qualified services.

Status Code

  • The request was successful.

  • The IAM access token specified by "x-auth-token" is invalid.

  • Internal error.

No Sample Response

This method does not specify any sample responses.

Create an IBM Cloud service instance of Hyperprotect DBaaS on the server indicated by the URL.

POST /services
Request

Custom Headers

  • Valid IAM access token

  • Set to "yes" to agree the license

Information of the user you want to create.

Response

The detail information about the service.

Status Code

  • The asynchronous request has been submitted successfully.

  • One or more parameter error.

  • The IAM access token specified by "x-auth-token" is invalid.

  • Internal error.

No Sample Response

This method does not specify any sample responses.

Delete an IBM Cloud service instance of Hyperprotect DBaaS on the server indicated by the URL

DELETE /services/{guid}
Request

Custom Headers

  • Valid IAM access token

Path Parameters

  • The guid ("cluster_id" in DBaaS term) of the service instance to be deleted.

Response

Status Code

  • OK

  • Can not find the service instance indicated by the guid.

  • Internal error.

No Sample Response

This method does not specify any sample responses.