Introduction

With IBM Analytics Engine you can create Apache Spark and Apache Hadoop clusters and customize these clusters by using scripts. You can work with data in IBM Cloud Object Storage, as well as integrate other Watson Data Platform services like IBM Watson Studio and Machine Learning. This set of APIs pertain to various actions you can perform on an IBM Analytics Engine service instance.

Service Endpoints

The endpoint URL used in the examples is not your actual service endpoint. To find out which URL to use, view the service credentials by clicking the service instance on the IBM Cloud console dashboard. Use the API URL under cluster_management section on the service credentials page.

For e.g. : The API URL will be in the following format

Creating an IAM bearer token

You use IBM® Cloud Identity and Access Management (IAM) tokens to make authenticated requests to IBM Analytics Engine APIs without embedding service credentials in every call. IAM authentication uses access tokens for authentication, which you acquire by sending a request with an API key. You can create a token in IBM Cloud using your API key or by using the IBM Cloud command line interface (CLI) as described here.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is a client side failure, and a 500 type response usually indicates a server side error.

Status code summary
Status code Description
200 OK The request was processed successfully.
400 Bad Request The request could not be processed, often due to a missing required parameter.
401 Unauthorized The request could not be processed due to insufficient permissions.
404 Not Found The requested resource does not exist.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests The request could not be processed due to too many concurrent requests against the API.
500 Server Error Your request could not be processed due to an internal server error.

Methods

List all Analytics Engines

Currently, you cannot fetch the list of all IBM Analytics Engine service instances through this REST API. You should use the IBM Cloud CLI instead. For example, ibmcloud resource service-instances --service-name ibmanalyticsengine

GET /v2/analytics_engines
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

No Sample Response

This method does not specify any sample responses.

Get details of Analytics Engine

Retrieves the following details of the IBM Analytics Engine service instance:

  • Hardware size and software package
  • Timestamps at which the cluster was created, deleted or updated
  • Service endpoint URLs

NOTE: No credentials are returned. You can get the IBM Analytics Engine service instance credentials by invoking the reset_password REST API.

GET /v2/analytics_engines/{instance_guid}
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • GUID of the service instance

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • No cluster associated with the given service instance guid

  • Internal Server Error

Example responses

Get state of Analytics Engine

The Analytics Engine could be in one of the following states

  • Preparing : A cluster is being created.
  • Active : The cluster is created and running.
  • Deleted : The cluster was deleted.
  • Failed : A cluster couldn't be created.
  • Expired : The service instance has expired. The cluster has been deleted.
  • ResizeFailed : The cluster couldn't be resized. The cluster will be reactivated based on the old settings.
GET /v2/analytics_engines/{instance_guid}/state
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • GUID of the service instance

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • No cluster associated with the given service instance guid

  • Internal Server Error

Example responses

Create an adhoc customization request

Creates a new adhoc customization request. Adhoc customization scripts can be run only once. They are not persisted with the cluster and are not run automatically when more nodes are added to the cluster.

POST /v2/analytics_engines/{instance_guid}/customization_requests
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • GUID of the service instance

Set of action scripts to run. The content of script property

vary based on the source_type. Use the example given below.

If your customization script is to be accessed using HTTP (without SSL), then

"script":
{


"source_type":
"http",
  "script_path": "http://host:port/path/to/bootstrap/script"
}

If your customization script is to be accessed using HTTPS, then

"script":
{

 "source_type":
"https",

 "source_props": {
      "username":
"user",

     "password":
"pwd"

  },
"script_path": "https://host:port/path/to/bootstrap/script"
}

If your customization script is stored in Bluemix Swift Object Store, then

"script":
{
  "source_type": "BluemixSwift",


"source_props":
{
    "auth_url":
"https://identity.open.softlayer.com",


  "user_id":
"xxxxxxxx",

   "password": "yyyyyyyyyy",
    "project_id":
"zzzzzzzzz",



 "region": "dallas"
  },
"script_path": "/myContainer/myFolder/path/to/bootstrap/script"
}

If your customization script is stored in Softlayer Swift Object Store, then

"script":
{


"source_type":
"SoftLayerSwift",
  "source_props": {
    "auth_endpoint":
"https://dal05.objectstorage.service.networklayer.com/auth/v1.0/",



 "username":
"xxxxxxx",
    "api_key": "yyyyyyy"
  },
"script_path":
"/myContainer/myFolder/path/to/bootstrap/script"
}

If your customization script is stored in IBM Cloud Object Store S3, then

"script":
{


"source_type":
"CosS3",
  "source_props": {
      "auth_endpoint":
"s3-api.dal-us-<geo>.objectstorage.service.networklayer.com",



   "access_key_id":
"xxxxxxx",
      "secret_access_key": "yyyyyy"


},
"script_path":
"/myBucket/myFolder/path/to/bootstrap/script"
}
Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Resource Not Found

  • Internal Server Error

Example responses

Get all customization requests run on an Analytics Engine

Retrieves the request_id of all customization requests submitted to the specified Analytics Engine cluster.

GET /v2/analytics_engines/{instance_guid}/customization_requests
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • service instance guid

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Resource Not Found

  • Internal Server Error

Example responses

Retrieve details of specified customization request ID

Retrieves the status of running the specified customization request, along with pointers to log files generated during the run.

GET /v2/analytics_engines/{instance_guid}/customization_requests/{request_id}
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • service instance guid

  • customization request id

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Resource Not Found

  • Internal Server Error

Example responses

Add nodes to the cluster

Resize the cluster by adding compute nodes.

Note: You can't resize the cluster if the software package on the cluster is deprecated or if the software package doesn't permit cluster resizing. See here.

POST /v2/analytics_engines/{instance_guid}/resize
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • service instance guid

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Resource Not Found

  • Internal Server Error

Example responses

Reset cluster password

Resets the cluster's password to a new system-generated crytographically strong value. The new password is included in the response and you should make a note of it. This password is displayed only once here and cannot be retrieved later.

POST /v2/analytics_engines/{instance_guid}/reset_password
Request

Custom Headers

  • Identity Access Management (IAM) bearer token.

Path Parameters

  • service instance guid

Response

Status Code

  • OK

  • Unauthorized

  • Forbidden

  • Resource Not Found

  • Method Not Allowed

  • Conflict

  • Internal Server Error

Example responses