Introduction

The IBM® Cloud Pak for Data Platform API connects to your Cloud Pak for Data platform to manage your user account. Administrators can also manage the users who have access to the platform, manage roles, and monitor the status of the platform.

Authentication

To authenticate to the API, you pass an access token in an Authorization header. The token is associated with a user name. To generate an access token, call the Get authorization token method.

Generating an access token. The response includes a token property.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -X POST -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

Authenticating to the API. Replace {token} with your details.

curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}{:port}/v1/{method}"

Service endpoint

The service endpoint is based on your IBM Cloud Pak deployment URL.

https://{cpd_cluster_host}{:port}/icp4d-api/v1/{method}

For example, if your instance is deployed at https://www.example.com:31843, you can access the APIs at https://www.example.com:31843/icp4d-api/v1/{method}.

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}{:port}/icp4d-api/v1/{method}"

Disabling SSL verification

All Cloud Pak for Data services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if absolutely necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

Example that disables SSL verification

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Error handling

IBM Cloud Pak for Data uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

Name Description
_messageCode_
string
An identifier of the response.
statusCode
integer
The HTTP response code.
exception
string
An explanation of the problem.
message
string
An explanation of the _messageCode_.

IBM Cloud Pak for Data docs

Methods

Get authorization token

Generate a bearer token from your Cloud Pak for Data credentials.

POST /v1/authorize

Request

  • curl -k -X POST -H "cache-control: no-cache" -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }

Get all users

Returns all users in the cluster.

GET /v1/users

Request

Custom Headers

  • The bearer token associated with a user name.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "UsersInfo": [
        {
          "approval_status": "approved",
          "authenticator": "default",
          "created_timestamp": "2018-10-08T21:53:14.855Z",
          "current_account_status": "enabled",
          "displayName": "admin",
          "email": "admin@example.com",
          "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
          "permissions": [
            "string"
          ],
          "role": "Admin",
          "uid": "1001",
          "user_roles": [
            "string"
          ],
          "username": "Admin"
        }
      ]
    }

Create user

Create a user account for the cluster.

POST /v1/users

Request

Custom Headers

  • The bearer token associated with a user name.

The new user.

Example:
  • curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"user_name\":\"{username}\",\"password\":\"{password}\",\"displayName\":\"{display_name}\",\"user_roles\":\"{user_roles}\",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "User": {
        "ID": "1001"
      }
    }

Get user information

Get details about one user.

GET /v1/users/{user_name}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The user name.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "UserInfo": {
        "approval_status": "approved",
        "authenticator": "default",
        "created_timestamp": "2018-10-08T21:53:14.855Z",
        "current_account_status": "enabled",
        "displayName": "admin",
        "email": "admin@example.com",
        "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
        "permissions": [
          "string"
        ],
        "role": "Admin",
        "uid": "1001",
        "user_roles": [
          "string"
        ],
        "username": "Admin"
      }
    }

Update user details

Update information about a user account.

PUT /v1/users/{user_name}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The user name.

The updated user information.

  • curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name}\", \"user_roles\":\"{user_roles}\", \"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Status Code

  • Success

  • Unauthorized

  • Not found.

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

Delete user

Delete a user from the cluster.

DELETE /v1/users/{user_name}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The user name.

  • curl -k -X DELETE -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

List all roles

Returns the user roles in the cluster.

GET /v1/roles

Request

Custom Headers

  • The bearer token associated with a user name.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "Roles": {
        "ID": "zen_administrator_role",
        "description": "Administrator role",
        "permissions": [
          "string"
        ],
        "role_name": "Administrator"
      }
    }

Create role

If the provided roles do not meet your needs, you can create other roles.

POST /v1/roles

Request

Custom Headers

  • The bearer token associated with a user name.

Information for creating a role

Example:
  • curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"role_name\":\"{name}\",\"description\":\"{description}\",\"permissions\":\"{permissions}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

Get role information

Get details about one role.

GET /v1/roles/{role_id}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The identifier of the role.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "RoleInfo": {
        "ID": "zen_administrator_role",
        "description": "Administrator role",
        "permissions": [
          "string"
        ],
        "role_name": "Administrator"
      }
    }

Update role

Update the name, description, and permissions associated with a role.

PUT /v1/roles/{role_id}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The identifier of the role.

The updated role information.

Example:
  • curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"role_name\":\"{role_name}\",\"description\":\"{role_description}\",\"permissions\":\"{permissions}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

Delete role

Delete a role from the cluster.

DELETE /v1/roles/{role_id}

Request

Custom Headers

  • The bearer token associated with a user name.

Path Parameters

  • The identifier of the role.

  • curl -k -X DELETE -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

List all permissions

Returns all permissions in the cluster.

GET /v1/permissions

Request

Custom Headers

  • The bearer token associated with a user name.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/permissions"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "Permissions": []
    }

Change my password

Change the logged in user's password.

POST /v1/changepassword

Request

Custom Headers

  • The bearer token associated with a user name.

Form Parameters

  • Current password.

  • New password.

  • curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"current_password\":\"{CURRENT_PASSWORD}\", \"new_password\":\"{NEW_PASSWORD}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/changepassword"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

Get my account information

Get details about the logged in user.

GET /v1/me

Request

Custom Headers

  • The bearer token associated with a user name.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/me"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "UsersInfo": [
        {
          "displayName": "admin",
          "email": "admin@example.com",
          "permissions": [
            "string"
          ],
          "role": "admin",
          "uid": "1001",
          "username": "Admin"
        }
      ]
    }

Update my information

Update the display name or email address for the logged in user.

PUT /v1/me

Request

Custom Headers

  • The bearer token associated with a user name.

The updated user information.

  • curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name \",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/me"

Response

Status Code

  • Success

  • Unauthorized

  • Internal error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

Check server status

Indicates whether your Cloud Pak for Data API server is running. is running

GET /v1/monitor

Request

No Request Parameters

This method does not accept any request parameters.

  • curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name \",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/monitor"

Response

Status Code

  • Success

  • Error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success"
    }

List the JSON data for all currently running jobs for a instance

GET /ae/{instance_id}/v2/jobs

Request

Path Parameters

  • instance id

Response

Job detail response

Status Code

  • List of running jobs

  • Instance id or api key not provided in the header

  • Instance id or api key provided but not authorized to create instance

  • Internal error occured

  • Job creation timed out

No Sample Response

This method does not specify any sample responses.

Start a job and return the uuid

POST /ae/{instance_id}/v2/jobs

Request

Path Parameters

  • instance id

Required job details

Response

Job detail response

Status Code

  • The metadata about the newly created job.

  • Instance id or api key not provided in the header

  • Instance id or api key provided but not authorized to create instance

  • Internal error occured

  • Job creation timed out

No Sample Response

This method does not specify any sample responses.

Get the JSON data for a job

GET /ae/{instance_id}/v2/jobs/{job_id}

Request

Path Parameters

  • instance id

  • job uuid

Response

Job detail response

Status Code

  • Get state of a job

  • Instance id or job id not valid

  • Instance id or api key not provided in the header

  • Instance id or api key provided but not authorized to create instance

  • Internal error occured

  • Job creation timed out

No Sample Response

This method does not specify any sample responses.

Kill a job

DELETE /ae/{instance_id}/v2/jobs/{job_id}

Request

Path Parameters

  • instance id

  • job uuid

Response

Status Code

  • Job deleted

  • Instance id or api key not provided in the header

  • Instance id or api key provided but not authorized to create instance

  • Job id not found

  • Internal error occured

  • Job deletion timed out

No Sample Response

This method does not specify any sample responses.