Introduction

Hyper Protect DBaaS is the next-level evolution of how data is stored in a highly secured enterprise cloud service. It is ideally suited for workloads with sensitive data and 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 and PostgreSQL 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 IBM Cloud Hyper Protect DBaaS for PostgreSQL and IBM Cloud Hyper Protect DBaaS for MongoDB.

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 Get an access token from IBM Cloud API Key.

Endpoint URLs

The following URLs represent the base URLs for the Hyper Protect DBaaS API endpoints. When you call the API, use the URL that corresponds to the region where your service instance is deployed. Add the path for each method to form the complete API endpoint for your requests.

  • Dallas: https://dbaas900.hyperp-dbaas.cloud.ibm.com:20000
  • Frankfurt: https://dbaas902.hyperp-dbaas.cloud.ibm.com:20000
  • Sydney: https://dbaas904.hyperp-dbaas.cloud.ibm.com:20000

Example request to a Dallas endpoint

curl -u "apikey:{apikey}" -X {request_method} "dbaas900.hyperp-dbaas.cloud.ibm.com:20000/api/v2/{user_id}/{method_endpoint}"

Replace {apikey}, {request_method}, {user_id}, and {method_endpoint} in this example with the values for your particular API call.

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.

Pagination

No endpoint currently returns paginated data.

Rate Limiting

No endpoint currently implements rate limiting.

Methods

Get an access token

Get an access token from IBM Cloud API Key. You will use the access token for future operations that require authentication.

GET /auth/token

Request

Custom Headers

  • The IBM Cloud API Key.

  • curl -X GET "https://<ip>:<port>/api/v2/auth/token" -H  "accept: application/json" -H  "api_key: <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
  • {
      "access_token": "eyJraWQiOiI......XmpBTIDdR5w",
      "user_id": "9025398753de792d09fa384d202f",
      "expires_in": 3600,
      "expiration": 1512161390
    }

Get service instances

List service instances of IBM Cloud Hyper Protect DBaaS on the server that is indicated by the URL.

GET /services

Request

Custom Headers

  • Valid IAM access token

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/services" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

List of service instances.

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 a service instance

Create a service instance of IBM Cloud Hyper Protect DBaaS on the server that is indicated by the URL.

POST /services

Request

Custom Headers

  • Valid IAM access token.

  • Set to "yes" to agree to the license.

Information about the user you want to create.

  • curl -X POST "https://<ip>:<port>/api/v2/{user_id}/services" -d '{"catalog": "hyperp-dbaas-postgresql", "name": <Service_Name>, "resource_group": "Default", "plan": "postgresql-free", "admin_name": "admin", "password": <password_for_admin>, "kms_instance":"<crn_of_kms_instance>", "kms_key":"<id_of_kms_key>"}' -H "x-auth-token: {access_token}" -H "content-type: application/json" -H "accept: application/json" -H "accept-license-agreement: yes"

Response

The response of create service API.

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.

Get a service instance

Get the service instance of IBM Cloud Hyper Protect DBaaS on the server that is indicated by the URL.

GET /services/{service_guid}

Request

Custom Headers

  • Valid IAM access token.

Path Parameters

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

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/services/{service_guid}" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

The detailed information about the service.

Status Code

  • Get service instance successfully.

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

  • Internal error.

No Sample Response

This method does not specify any sample responses.

Delete a service instance

Delete a service instance of IBM Cloud Hyper Protect DBaaS on the server that is indicated by the URL.

DELETE /services/{service_guid}

Request

Custom Headers

  • Valid IAM access token.

Path Parameters

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

  • curl -X DELETE "https://<ip>:<port>/api/v2/services/{service_guid}" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

OK message object.

Status Code

  • The asynchronous request has been submitted successfully.

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

  • Internal error.

Example responses
  • {
      "message": "ok"
    }

Get database cluster details

Get the detailed information about the specific database cluster that is indicated by its ID.

GET /clusters/{cluster_id}

Request

Path Parameters

  • The ID of a cluster object.

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/clusters/{cluster_id}" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

An object that shows detailed information about a cluster that has ID, name, state, three replicas, and so on.

Status Code

  • The request was successful.

  • Parameter error.

  • Unauthorized.

  • Cluster unavailable.

  • Internal error.

Example responses
  • {
      "id": "7f7aebb87d4fa262a18c8faca505b92a",
      "region": "eu-de",
      "name": "replica1",
      "state": "RUNNING",
      "reason": "",
      "db_type": "mongodb",
      "log_url": "https://logging.eu-fra.bluemix.net/app/#/kibana5/discover?_g=()&_a=(columns:!(_source),interval:auto,query:(query_string:(analyze_wildcard:!t,query:'cluster_id_str:3d60c20a4709526ad299236881f9d54c')),sort:!('@timestamp',desc))",
      "metric_url": "https://metrics.stage1.ng.bluemix.net",
      "replica_count": 3,
      "resource": {
        "cpu": 2,
        "memory": "20 GiB",
        "storage": "20 TiB"
      },
      "external_key": {
        "kms_instance": "crn:v1:staging:public:kms:us-south:a/23a24a3e3fe7a115473f07be1c44bdb5:9eeb285a-88e4-4378-b7cf-dbdcd97b5e4e::",
        "kms_key": "95d5e441-27e7-4715-a8a8-357871722585"
      },
      "nodes": [
        {
          "id": "0286c5b91f9f079d9f1df91fceb391f9",
          "replica_state": "PRIMARY",
          "replication_lag": 0,
          "node_state": "RUNNING",
          "reason": "",
          "stopped_reason": "",
          "ip": "9.152.161.59:27019",
          "created_at": "2017-06-22T19:10:51Z",
          "updated_at": "2017-06-22T19:10:51Z",
          "is_metric_enabled": false,
          "is_logging_enabled": false
        },
        {
          "id": "f197da44dbe3fca45e0ddbbb174d2d3f",
          "replica_state": "SECONDARY",
          "replication_lag": 0,
          "node_state": "RUNNING",
          "reason": "",
          "stopped_reason": "",
          "ip": "9.152.161.58:27019",
          "created_at": "2017-06-22T19:10:51Z",
          "updated_at": "2017-06-22T19:10:51Z",
          "is_metric_enabled": true,
          "is_logging_enabled": false
        },
        {
          "id": "a93156690ecb7d741cd1a37ac0715ae3",
          "replica_state": "SECONDARY",
          "replication_lag": 0,
          "node_state": "RUNNING",
          "reason": "",
          "stopped_reason": "",
          "ip": "9.152.161.60:27019",
          "created_at": "2017-06-22T19:10:51Z",
          "updated_at": "2017-06-22T19:10:51Z",
          "is_metric_enabled": true,
          "is_logging_enabled": true
        }
      ],
      "created_at": "2017-06-22T19:10:51Z",
      "updated_at": "2017-06-22T19:10:51Z"
    }

List database users

List the information about all the users in the specified database cluster that is indicated by its ID.

GET /clusters/{cluster_id}/users

Request

Path Parameters

  • The ID of a cluster object.

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/clusters/{cluster_id}/users" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

Object of information about users.

Status Code

  • The request was successful.

  • Unauthorized.

  • Cluster unavailable.

  • Internal error.

Example responses
  • {
      "users": [
        {
          "auth_db": "admin",
          "name": "admin"
        },
        {
          "auth_db": "mydb",
          "name": "syrena"
        }
      ]
    }

Get database user details

Get the detailed information about the user of a specified database cluster that is indicated by its ID.

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

Request

Path Parameters

  • The ID 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". For PostgreSQL, it should be only "username"; for example: "syrena".

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/clusters/{cluster_id}/users/{db_user_id}" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

A user information object received.

Status Code

  • The request was successful.

  • Unauthorized.

  • Cluster unavailable, or the user ID not found.

  • Internal error.

Example responses
  • {
      "name": "syrena",
      "auth_db": "mydb",
      "db_access": [
        {
          "db": "admin",
          "privileges": [
            "userAdminAnyDatabase"
          ]
        },
        {
          "db": "test",
          "privileges": [
            "readWrite"
          ]
        }
      ]
    }

List databases

Get a list of all databases in a specified database cluster that is indicated by its ID.

GET /clusters/{cluster_id}/databases

Request

Path Parameters

  • The ID of a cluster object.

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/clusters/{cluster_id}/databases" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

Information about all databases in a cluster.

Status Code

  • The request was successful.

  • Unauthorized.

  • Cluster unavailable.

  • Internal error.

Example responses
  • {
      "total_size": 251658240,
      "databases": [
        {
          "name": "admin",
          "size_on_disk": 83886080
        },
        {
          "name": "local",
          "size_on_disk": 83886080
        },
        {
          "name": "test",
          "size_on_disk": 83886080
        }
      ]
    }

List database log files

List the latest log files of the node that is indicated by its ID.

GET /nodes/{node_id}/logs

Request

Path Parameters

  • The ID of a node object.

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/nodes/{node_id}/logs" -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

Logs object.

Status Code

  • The request was successful.

  • Unauthorized.

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

  • Internal error.

Example responses
  • {
      "logs": [
        {
          "filename": "mongod.log",
          "size": 6800,
          "last_modified": "2018-06-05 05:04:27"
        },
        {
          "filename": "mongod.log.20180604-1528094566",
          "size": 531015965,
          "last_modified": "2018-06-04 06:42:46"
        },
        {
          "filename": "postgresql.log.20180812-030816",
          "size": 7118432,
          "last_modified": "2018-08-12 03:08:16"
        }
      ]
    }

Get log details

Get the content of the specified log file of the node that is indicated by its ID.

GET /nodes/{node_id}/logs/{log_name}

Request

Custom Headers

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

Path Parameters

  • The ID of a node object.

  • The name of the log file.

  • curl -X GET "https://<ip>:<port>/api/v2/{user_id}/nodes/{node_id}/logs/{log_name}" -o {log_name} -H "x-auth-token: {access_token}" -H "accept: application/json"

Response

File downloaded.

Status Code

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

  • Unauthorized.

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

  • Internal error.

No Sample Response

This method does not specify any sample responses.