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.

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/v1/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"
    }

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/v1/{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 the license

information about the user you want to create.

  • curl -X POST \
    "https://<ip>:<port>/api/v1/{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/v1/{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/v1/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 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/v1/{user_id}/clusters/{cluster_id}" \
    -H "x-auth-token: {access_token}" \
    -H "accept: application/json"
Response

An object which shows detailed information about a cluster which 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"
      },
      "instances": [
        {
          "id": "0286c5b91f9f079d9f1df91fceb391f9",
          "replica_state": "PRIMARY",
          "replication_lag": 0,
          "instance_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,
          "instance_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,
          "instance_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/v1/{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".

  • curl -X GET \
    "https://<ip>:<port>/api/v1/{user_id}/clusters/{cluster_id}/users/mydb.syrena" \
    -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/v1/{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 /instances/{instance_id}/logs
Request

Path Parameters

  • The ID of an instance object.

  • curl -X GET \
    "https://<ip>:<port>/api/v1/{user_id}/instances/{instance_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 instance 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 /instances/{instance_id}/logs/{log_name}
Request

Custom Headers

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

Path Parameters

  • The ID of an instance object.

  • The name of the log file.

  • curl -X GET \
    "https://<ip>:<port>/api/v1/{user_id}/instances/{instance_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 instance ID.

  • Internal error.

No Sample Response

This method does not specify any sample responses.