Creating a Watson Assistant service instance programmatically

Use the application programming interface to create a Watson Assistant 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 Assistant 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 Assistant 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 token that you can pass with the RESTful API request to prove that you are authorized to do so. Follow the steps that are described in Generating an authorization token or API key.

Creating the service instance

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

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}'
```
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. For example, wa-service-instance.

${PROJECT_CPD_INSTANCE}

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

Example

The following example shows how to get the access token, and then make the API request to create the service instance. In this scenario, IAM is not enabled and the access token is stored so that it can be referenced in the POST request.

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}'
```
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 Assistant service instance. In this example, the project name is zen.

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": "assistant",
  "addon_version": "4.6",
  "create_arguments": {
    "deployment_id": "zen-wa",
    "parameters" : {
     "serviceId": "assistant",
      "url": "wa-store.zen.svc.cluster.local:443/csb/v2/service_instances",
      "watson": true
    }
  },
  "display_name": "wa-service-instance",
  "namespace": "zen"
  }'

Listing the service instances

The following example list service instances:

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

Deleting the service instance

The following example deletes the service instance:

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