Introduction

Using IBM Watson Machine Learning, you can build analytic models and neural networks, which are trained with your own data, that you can deploy for use in applications. Watson Machine Learning provides a full range of tools and services, so you can build, train, and deploy Machine Learning models. Choose from tools that fully automate the training process for rapid prototyping to tools that give you complete control to create a model that matches your needs.

For more information about how to use IBM Watson Machine Learning (WML), see Data science solutions.

There is a specialized python library that is available to access this REST API here.

Endpoint URLs

The base URLs for Watson Machine Learning API endpoints come from the cluster and add-on service instance. The URL follows this pattern:

https://{cpd_cluster}/ml/v4/

{cpd_cluster} represents the name or IP address of your deployed cluster. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

To find the base URL, view the details for the service instance from the Cloud Pak for Data web client.

Use that URL in your requests to Watson Machine Learning.

Endpoint example

curl -k -X {request_method} \
-H "Authorization: Bearer {token}" \
"https://{cpd_cluster}/ml/v4/{method}"

Disabling SSL verification

Watson Machine Learning uses 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 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.

Authentication

A bearer token from IBM Cloud Pak for Data is required to use any of the Watson Machine Learning APIs.

For more information, see the Authorization section of the Cloud Pak for Data API reference.

Example request that uses an API key to retrieve the token

curl -k -X POST \
"https://cpd_cluster_host/icp4d-api/v1/authorize" \
  -H "cache-control: no-cache" \
  -H "content-type: application/json" \
  -d "{\“username\”:\“admin\”,\“password\”:\“password\”}"

Response

{
  "username": "admin",
  "role": "Admin",
  "permissions": [
    "administrator"
  ],
  "sub": "admin",
  "iss": "KNOXSSO",
  "aud": "DSX",
  "uid": "999",
  "authenticator": "default",
  "access_token": "eyJraWQiOiIyMDE3MDgwOS0wMDowMDowMCIsImFsZyI6...",
  "_messageCode_": "success"
}

Use the value of the access_token property from the example request. Set the access_token value as the authorization header parameter for requests to the Watson Machine Learning APIs. The format is Authorization: Bearer {access_token_value}:

Authorization: Bearer eyJraWQiOiIyMDE3MDgwOS0wMDowMDowMCIsImFsZyI6IlJTMjU2In0...

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

| HTTP Code | Description | Recovery | |-----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 | Success | The request was successful. | | 400 | Bad Request | The input parameters in the request body are either incomplete, or in the wrong format, or some other input validation failed. Be sure to include all required parameters in your request and check the request body. | | 401 | Unauthorized | You are not authorized to make this request. Log in and try again or provide a valid token. For more information about logging in, see the Authentication section. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized. | | 404 | Not Found | The requested resource was not found. |

Error response

| Name | Description | |--------|-------------------------------------------------------------------------------------------------------| | trace | An identifier that can be used to trace the request. This can be set using X-Global-Transaction-Id. | | errors | The list of errors. |

Errors

| Name | Description | |-----------|-------------------------------------------------------------------------| | code | A simple string code that should convey the general sense of the error. | | message | The message that describes the error. | | more_info | A reference to a more detailed explanation when available. |

Additional headers

Some additional headers might be required to make successful requests to the API. Those additional headers are described below.

An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to X-Global-Transaction-Id and the value is anything that you choose.

If there is not a transaction ID that is passed in, then one is generated randomly.

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. See API Handbook for more details about date based API versioning. When there is a change to the API in a backwards-incompatible way, a new version date is published. Send the version parameter with every API request.

The service uses the API version for the date that you specify or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app and do not change it until your app is ready for a later version.

Deployed Version Dates

2021-05-01

The creation of deployment jobs is now fully asynchronous. What this means is that the creation of the job will not return the platform_jobs section in the response, instead poll the job using the deployment-jobs-get operation until the platform_jobs section is provided in the response.

Data References

Accessing data in a remote location (such as a Cloud Object Storage bucket, or an SQL/no-SQL database) requires the use of connection_asset or data_asset or fs reference types. These types are created within a space or a project and are referenced in WML requests to represent input data and results locations. These types contain two parameter objects, connection and location, which require different values to be supplied based on the reference type. Using a data_asset, requires an href to be supplied to the location object whereas using a connection_asset requires the connection_id for the connection object and different location fields depending on the data source type, see Data reference Description for details.

Example data_asset payload:

"training_data_references": [{
  "type": "data_asset",
  "location": {
    "href":"/v2/assets/<asset_id>?space_id=<space_id>"
  }
}]

Example connection_asset payload:

"training_data_references": [{
  "type": "connection_asset",
  "connection": {
    "id": "<connection_guid>"
  },
  "location": {
    "<wdp-properties depending on the type>"
  }
}]

Example url payload (Decision Optimization only):

"training_data_references": {
  "type": "url",
  "id": "diet_food.csv",
  "connection": {
    "verb": "GET",
    "url": "https://myserver.com/diet_food.csv",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded"
    }
  },
  "location": {
  }
}

Example fs payload:

"training_data_references": [{
  "type": "fs",
  "id": "customers.csv",
  "location": {
    "path": "/data/customers.csv"
  }
}]

Watson Machine Learning for IBM Cloud Pak 5.4.0 | IBM Cloud API Docs