Skip to main contentIBM Cloud
  • Start for free

    • 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

    • api_key
      string

      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

    Response Body

    AccessToken

    The access token of one user.

    Status Code

    • 200

      The request was successful.

    • 400

      The API Key is needed as a parameter.

    • 500

      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

    • x-auth-token
      string

      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

    Response Body

    ServiceInstances

    List of service instances.

    Status Code

    • 200

      The request was successful.

    • 401

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

    • 500

      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

    • x-auth-token
      string

      Valid IAM access token.

    • accept-license-agreement
      string

      Set to "yes" to agree to the license.

    Request Body

    CreateService

    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

    Response Body

    CreateServiceResponse

    The response of create service API.

    Status Code

    • 202

      The asynchronous request has been submitted successfully.

    • 400

      One or more parameter error.

    • 401

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

    • 500

      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

    • x-auth-token
      string

      Valid IAM access token.

    Path Parameters

    • service_guid
      string

      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

    Response Body

    Service

    The detailed information about the service.

    Status Code

    • 200

      Get service instance successfully.

    • 404

      Can not find the service instance indicated by the guid.

    • 500

      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

    • x-auth-token
      string

      Valid IAM access token.

    Path Parameters

    • service_guid
      string

      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

    Response Body

    MsgOK

    OK message object.

    Status Code

    • 202

      The asynchronous request has been submitted successfully.

    • 404

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

    • 500

      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

    • cluster_id
      string

      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

    Response Body

    Cluster

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

    Status Code

    • 200

      The request was successful.

    • 400

      Parameter error.

    • 401

      Unauthorized.

    • 404

      Cluster unavailable.

    • 500

      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

    • cluster_id
      string

      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

    Response Body

    GetUsers

    Object of information about users.

    Status Code

    • 200

      The request was successful.

    • 401

      Unauthorized.

    • 404

      Cluster unavailable.

    • 500

      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

    • cluster_id
      string

      The ID of a cluster object.

    • db_user_id
      string

      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

    Response Body

    GetUser

    A user information object received.

    Status Code

    • 200

      The request was successful.

    • 401

      Unauthorized.

    • 404

      Cluster unavailable, or the user ID not found.

    • 500

      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

    • cluster_id
      string

      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

    Response Body

    Databases

    Information about all databases in a cluster.

    Status Code

    • 200

      The request was successful.

    • 401

      Unauthorized.

    • 404

      Cluster unavailable.

    • 500

      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

    • node_id
      string

      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

    Response Body

    LogList

    Logs object.

    Status Code

    • 200

      The request was successful.

    • 401

      Unauthorized.

    • 404

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

    • 500

      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

    • Accept
      string

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

    Path Parameters

    • node_id
      string

      The ID of a node object.

    • log_name
      string

      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

    Response Body

    binary

    File downloaded.

    Status Code

    • 200

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

    • 401

      Unauthorized.

    • 404

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

    • 500

      Internal error.

    No Sample Response

    This method does not specify any sample responses.