Creating a Watson Discovery service instance programmatically

Use the application programming interface to create a Watson Discovery service instance.

This task is equivalent to provisioning a service instance from the Cloud Pak for Data web client. For more information, see Creating a Watson Discovery service instance from the web client. Alternatively, you can use the command-line interface to create a service instance. For more information, see Creating a Watson Discovery service instance from the command line.

Required role: To use this API, you must have the can_provision permission in Cloud Pak for Data.

Prerequisite step

Before you can use the API, you must get an API key that you can use to get a token that you can pass with the RESTful API request. Follow the steps that are described in Generating API keys for authentication.

Creating the service instance

To create a service instance by using the API, complete the following step.

The following command gets the hostname for the Cloud Pak for Data cluster where you want to create the instance.
```
oc get route cpd -n $PROJECT_CPD_INSTANCE -ojsonpath='{.spec.host}'
```
You will pass this hostname as the <host> variable in subsequent API requests.
Send a POST request to create a service instance.
Update the following variables with the right values for your deployment:

<host>

The hostname that you retrieved in the previous step.

<token>

The authorization token that you obtained when you completed the prerequisite step.

${VERSION}

Environment variable for the version of the Cloud Pak for Data software that is installed.

<instance-name>

Name that you want to use for the service instance. This name is displayed in the Instances page of the Cloud Pak for Data web client. The name can contain alphanumeric characters, spaces, dashes, underscores, and periods.

${PROJECT_CPD_INSTANCE}

Environment variable for the project name (formerly namespace) that was defined before the service was installed. For more information, see Setting up installation environment variables.
```
curl --insecure --request POST --url <host>/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>" \
  --header 'Content-Type: application/json' \
  --data "{
    \"addon_type\": \"discovery\", 
    \"addon_version\": \"${VERSION}\", 
    \"create_arguments\": { 
      \"deployment_id\": \"$PROJECT_CPD_INSTANCE-wd\",
      \"parameters\" : {
        \"serviceId\": \"discovery\", 
        \"url\": \"https://wd-discovery-gateway.$PROJECT_CPD_INSTANCE.svc.cluster.local:60443/v2/service_instances\", 
        \"watson\": true 
       } 
     }, 
     \"display_name\": \"<instance-name>\", 
     \"namespace\": \"$PROJECT_CPD_INSTANCE\" 
   }"
```

Example

The following example shows how to get the access token, and then make the API request to create the service instance.

Submit the following command to get the hostname for the Cloud Pak for Data cluster where you want to create the instance.
```
oc get route cpd -n $PROJECT_CPD_INSTANCE -ojsonpath='{.spec.host}'
```
The hostname that is returned in this example is cpd.apps.my.cluster.example.com. The hostname is then passed as the <host> variable in subsequent API requests.
Get a platform API key.
1. Get an access token for the Cloud Pak for Data cluster. This request uses basic authentication; it provides the user credentials for a user in the administrative role who can provision service instances.
```
curl --request POST --user jdoe:mypassword \
--url <host>/v1/preauth/validateAuth
```
  The response contains an accessToken field that contains a bearer token. Store the token so that you can specify it in the next step.
2. Generate an API key that you can use to identify yourself when you submit RESTful API requests. This request is authenticated with the token that was returned in the previous step.
  Note: The API key that is generated by this request replaces the existing API key that is associated with your user ID.
```
curl --request POST \
--url <host>/usermgmt/v1/user/apiKey \
--header "Authorization: Bearer <token>"
```
  This response contains an apiKey field that contains the API key. Store the key somewhere safe. You cannot recover this key if you lose it.
Use the API key to create a token that authorizes you to send API requests. Submit the following POST request to create the token.
The request uses basic authentication; it provides the user credentials for the same user who created the API key and has permission to provision service instances.
```
curl --request POST --user jdoe:mypassword \
--url <host>/icp4d-api/v1/authorize
```
If a message about a certificate error is displayed, you can add the --insecure argument to the request to disable certificate validation.
In the body of the request, specify the API key that you obtained in the previous step. The user name must be the same name that is used to authenticate this request.
```
{
  "username":"jdoe",
  "api_key":"amgbHu4VwDXRho9yLvF2IN5QkUVMWykjAolxYYQp"
}
```
The token that you will use to authenticate requests is returned in the token field of the response. Copy the token value so that you can use it later.

The following POST request creates the Watson Discovery service instance.

In this example, the project name is zen.

The URL that is specified in the url parameter in the request body is used by the Watson gateway microservice, which is a service that manages API requests for the Watson services.

Example request:

curl --request POST --url https://cpd.apps.my.cluster.example.com/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>" \
  --header 'Content-Type: application/json' \
  --data "{
    \"addon_type\": \"discovery\",
    \"addon_version\": \"4.6.2\",
    \"create_arguments\": {
      \"deployment_id\": \"zen-wd\",
      \"parameters\" : {
        \"serviceId\": \"discovery\", 
        \"url\": \"https://wd-discovery-gateway.zen.svc.cluster.local:60443/v2/service_instances\",
        \"watson\": true
       }
     },
     \"display_name\": \"My instance\",
     \"namespace\": \"zen\"
   }"

The response contains an id parameter that contains the instance ID of the instance that is created. Make a note of the instance ID.

Example response:

{
    "id": "1670881541354464"
}

Completing Watson Discovery tasks

After you create the instance, you can add projects and data by using the Watson Discovery APIs.

To use the APIs, complete the following steps:

To use the service APIs, submit requests to the appropriate endpoint for the method that you want to use by using the following syntax:
```
https://<url>/<method>
```
You can authenticate the request by passing the same bearer token that you used to provision the service instance.
To construct the URL to use in the <url> segment of the request, replace the <host>, <deployment_id>, and <instance_id> segments of the URL with values from your deployment.
```
https://<host>/discovery/<deployment_id>/instances/<instance_id>/api
```
The method segment of the request defines the action that you want to take. To create a project, the method to use is v2/projects.
To create a Document Retrieval project in the service instance that you created, you can send a POST request to the following endpoint:
```
https://<host>/discovery/<deployment_id>/instances/<instance_id>/api/v2/projects
```
For example:
```
curl --request POST --url https://cpd.apps.my.cluster.example.com/discovery/zen-wd/instances/1670881541354464/api/v2/projects?version=2020-08-30
```
In the body of the request, define the project:
```
{
  "name": "My new project",
  "type": "document_retrieval" 
}
```

For more information about the methods that you can use to work with Watson Discovery programmatically, see the Watson Discovery API documentation.

Listing the service instances

The following example syntax lists the Cloud Pak for Data service instances:

curl --request GET \
  --url https://<host>/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>"

Deleting the service instance

The following example syntax shows you how to delete a service instance that you specify by its instance ID:

curl --request DELETE \
  --url https://<host>/zen-data/v3/service_instances/<instanceId> \
  --header "Authorization: Bearer <token>"