This tutorial shows you how to obtain access to the Watson Analytics REST API and invoke API methods.
To use the Watson Analytics REST API, it is important that you understand the basics of RESTful web services and JSON representations.
- In a web browser, go to API Explorer.
- Click Sign up for free at the top-left of the screen.
- On the Try Watson Analytics API page, create a new IBMid, and click Continue.
- Get the confirmation code in your email and type the confirmation code.
- Click Try Watson Analytics API. This process might take a few moments. Click Refresh to view the status.
- Check your email for a couple of emails. One is a notification that your Watson Analytics API Trial subscription is ready. The other is a confirmation that your new IBMid is ready to use.
- After the status is Active, click Launch Service and sign into IBM API Explorer using your IBMid.
- Select a display name for your new developerWorks profile and click Submit. You can also set up access to IBM Bluemix, but access is not required to use the Watson Analytics API.
- In API Explorer, select Watson Analytics.
- Navigate to the Security > Keys section in the table of contents.
- In the KEYS dropdown list, select #1 – Key 1.
- Click the Hide button to show the X-IBM-Client-Id and X-IBM-Client_Secret values. Record them for future use. Make sure to keep them in secure location.
- You can now start to use the Watson Analytics API.
The next step is to register the client in Watson Analytics.
Register the API client ID and the application information
Use the /oauth2/v1/config operation to register your application’s information in Watson Analytics. Execute this operation in a server component. You only need to call this operation once unless the client ID changes. Be sure to enter the code on one line and to observe the spaces.
curl -v -X PUT -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "Content-Type: application/json" -d '{"clientName": "The Sample Outdoors Company", "redirectURIs": "https://example.com:5443", "ownerName": "John Smith", "ownerEmail": "[email protected]", "ownerCompany": "example.com", "ownerPhone": "555-123-4567"}' https://api.ibm.com/watsonanalytics/run/oauth2/v1/config
All fields are required.
A redirect URI is the callback entry point of the application. Specify a URI or list of URIs separated by spaces for each application that you want the Watson Analytics API to redirect to.
Get an authorization code
The authorization code is a one-time code that your server can exchange for an access token. Use the /clientauth/v1/auth operation to construct a URL that your
application calls to generate the authorization code. This operation must be executed in a browser.
https://api.ibm.com/watsonanalytics/run/clientauth/v1/auth?response_type=code&client_id=YOUR_CLIENT_ID&scope=userContext&redirect_uri=https://localhost:5443
When invoking the request in a browser, a pop-up window requests your permission to grant your application access to Watson Analytics. Click OK to proceed.
For example, the following pop-up allows an application called “APIc” to use the Manage and schedule assets scope within Watson Analytics.
The response is in a callback URL that uses the redirect URI. The state parameter is used by the client to authenticate itself. When it receives a state parameter, the authorization server returns it to the client verbatim by tacking it onto the client’s callback URL.
If no errors occur, the callback URL also includes an authorization code that is valid for a short time.
https//localhost:5443/code?code=YOUR_AUTHORIZATION_CODE&state=YOUR_OPAQUE_VALUE
If an error occurs, the callback URL appears as follows:
https//localhost:5443/code?error=ERROR_CODE&error_description=ERROR_MESSAGE&state=YOUR_OPAQUE_VALUE
Exchange the authorization code for an access token
Before your application can access private data using the Watson Analytics API, it must obtain an access token that grants access to the API.
Use the /oauth2/v1/token operation to get the access token your application will use in all subsequent Watson Analytics API operations. This operation should be executed in a server component.
curl -v -X POST -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "Content-Type: application/x-www-form-urlencoded" --data "grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE" https://api.ibm.com/watsonanalytics/run/oauth2/v1/token
Before an access token is granted, the end user of your application must grant permissions to your application to access their account in the Watson Analytics UI. Some of the permissions requested might be ‘userContext’ (which allows your application to manage and delete assets), ‘storyBooks_r’ (to view Expert Storybooks in a user’s account), ‘storyBooks_w’ (to create Expert Storybooks in a user’s account), and ‘storyBooks_c’ (to change Expert Storybooks in a user’s account).
The following is an example of a response from a successful request:
{
"token_type": "Bearer",
"access_token": "NbrAbYeRx93bZu3lDvM7JbxgBItj7VhZ
/m0MDN54KTaCQl3NjpgVaPoATTxpittle6QdUQDkUAncdr
/lBNVLRd7aBxoklftwjDNKs8sVrp6zbT15XMF
/bY0zSE/SfPaAMIvzUfS
/sEwlSBAta0MI2lTceD+9hP7aQ5Z8PzFQj8zubP4xSpTbU4bEhJbANnE4ybLmkWsPWhRaWZGw4e37R3
/+QvedEcJPs0sMLYPOLCj6NqkAY382PVCiop2mS9WIdorzu2kg4d1WKd
/Mzr6PeIU59uNpFBpqlih4duLHO4A8830qm7bVd+9XX5qj1vAsMUnDmbfnTvY/c=",
"expires_in": "3600",
"scope": "userContext",
"refresh_token": "NheAcYaVx37bZu98DsN6GbdgCGej8VhB"
}
Note: You can obtain access to multiple scopes by specifying more than one scope; separated by a URL-encoded space. This example illustrates a request for three scopes (ie. userContext, storybook_r, and storybook_w):
https://api.ibm.com/watsonanalytics/run/clientauth/v1/auth?scope=userContext%20storybooks_r%20storybooks_w&response_type=code&redirect_uri=https://localhost:5443&client_id=YOUR_CLIENT_ID
Using the Watson Analytics API
This part of the tutorial shows you how to get information about the current user, create an empty data asset, load data into the data asset, and monitor the status of load jobs.
Get metadata about the current user
This operation returns information about the current user, including their first name, last name, email address, user ID and tenant ID.
It also returns the name and ID of the user’s role, the maximum number of rows and columns and maximum size that a data asset in their tenant can contain, and information about how much disk space their tenant can consume.
curl -v -X GET -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.ibm.com/watsonanalytics/run/accounts/v1/me
The following is an example of a response from a successful request:
{
"tenantId": "123456",
"loginId": "[email protected]",
"lastName": "Smith",
"accountId": "6789",
"userId": "1234",
"role": {
"id": "2",
"name": "administrator"
},
"emailAddress": "[email protected]",
"licenses": {
"total": 300,
"used": 250
},
"tenantQuota": {
"maxDatasetNumberOfColumns": 500,
"maxDatasetNumberOfRows": 10000000,
"currentDiskUsage": 5674586955,
"maxDiskSpace": 107374182400,
"maxUploadSpace": 10737418240
},
"displayName": "John Smith",
"firstName": "John"
}
The values for currentDiskUsage, maxDiskSpace, and MaxUploadSpace are in bytes.
If you are not authorized to access information about this user, the request fails and a 401 status code is returned.
Create an empty data asset
This operation creates an empty data asset. The name of the data asset can’t contain a “/” or a “\”, otherwise you get a 500 error response. If a data asset doesn’t contain any data, the data asset is shown to be in an “Uploading” state in the Watson Analytics UI (“Transferring” in Watson Analytics classic) and users are limited in what they can do with the data asset.
curl -v -X POST -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" https://api.ibm.com/watsonanalytics/run/data/v1/datasets -d '{ "description" :"1234" , "name" :"1234" }'
The following is an example of a response to a successful request:
{
"id":"12e3cfb4-56bd-7aba-a8ce-901d2c3d4567",
"name": "Data Asset 1"
}
If the data asset’s name already exists, the request fails and a 409 status code is returned along with the following:
{
"id": "12e3cfb4-56bd-7aba-a8ce-901d2c3d4567",
"message": "Unable to create a data asset with the name ('Data asset 1') because an object with the same name already exists.
/Try again with a different name.",
"code": "409",
"developer": "The operation 'POST /datasets' failed because the data asset name ('Data set JH2') already
/exists with ID ('12e3cfb4-56bd-7aba-a8ce-901d2c3d4567')."
}
Load a data asset with content
This operation uploads the content from a file into the specified data asset.
The data can be in several different formats. You must specify the appropriate content type for the format.
- CSV file format. Use the text/csv content type.
- Microsoft Excel spreadsheet (.xls or .xlsx) file format. Use the application/vnd.ms-excel content type.
- Open Office spreadsheet (.ods) file format. Use the application/vnd.openxmlformats-officedocument.spreadsheetml.sheet content type.
- Compressed CSV file format. This is a CSV file that is compressed in gzip format. No other compression formats (such as zip or pkzip) are supported. The file is automatically uncompressed after it is uploaded. Use the text/csv+gzip content type.
curl -v -X PUT -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type:text/csv" https://api.ibm.com/watsonanalytics/run/data/v1/datasets/ID_OF_DATA_SET/content -d "YOUR_DATA"
The -d option contains the data to be uploaded. The following is an example of the -d option with data:
-d "Province,Population density,Area,Population,
Ontario,97,83858,8169929
Quebec,337,30510,11007020
Alberta,111,547030,63601002
Manitoba,233,357021,81799600
British Columbia,393,41526,16824400"
A response code of 202 indicates that the request was accepted but doesn’t indicate the status of the job.
Load a data asset with content in segments
This operation uploads the content from a delimited data file (CSV, XLS) into the specified data asset in segments.
The maximum size of a segment is 25 MB, but for best results for a server operation, use segments that are no more than 10 – 20 MB in size.
You can submit segments in parallel. The limit is the size of your thread pool. The segmentId is alphanumeric, so number your segments 01, 02, 03, … 11, 12 to keep them in order.
To indicate that there are no more segments to upload, submit a PUT /datasets/[id]/content statement with an empty body. You can’t append data to an existing data asset after you submit an empty body. To replace all data that’s in a data asset, first delete the data asset’s content.
curl -v -X PUT -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type:text/csv" https://api.ibm.com/watsonanalytics/run/data/v1/datasets/ID_OF_DATA_SET/content/ID_OF_SEGMENT -d "YOUR_DATA"
The -d option contains the data to be uploaded.
A response code of 204 indicates that the request was accepted but doesn’t indicate the status of the job.
Check on the status of the data upload job
This operation returns the upload status of the specified data asset, including how much the upload has progressed, the phase or status of the upload, and details of any errors that occurred during the upload.
curl -v -H "X-IBM-Client-Id:YOUR_CLIENT_ID" -H "X-IBM-Client-Secret:YOUR_CLIENT_SECRET" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.ibm.com/watsonanalytics/run/data/v1/datasets/ID_OF_DATA_SET/job
The following is an example of a response indicating that the request has completed successfully:
{
"progress": 100,
"phase": "valid"
}
A response code of 404 indicates that the job was not found.
Code samples
We have some simple open-source IBM Watson Analytics code samples available for you to try out.
Better yet, because they’re open source, you can use them as a starting point for your applications. They’re available for some of today’s most popular languages:
- Java
- Node.JS
- Ruby on Rails
Get the samples from the Watson Analytics area on GitHub.
