Create a Watson Assistant service instance programmatically

README.md

Creating a service instance programmatically.

• The examples below use curl but any language can be used as it's just REST calls.
• All the APIs used in this tutorial are documented here: https://cloud.ibm.com/apidocs
• Make sure you read the Resource Controller API: https://cloud.ibm.com/apidocs/resource-controller#create-provision-a-new-resource-instance
• Information about apikeys and tokens can be found here: https://cloud.ibm.com/docs/iam?topic=iam-iamtoken_from_apikey
• Watson Assistant is used as example below but it this steps can be applied to any service.

1. Create a platform apikey

In order to create/delete service instances programmatically a platform apikey needs to be used. The GIF below shows the steps to create a platform apikey

Example apikey CiPOUh-NboDCDYXXy8m2NhtT4GnZDAKyV99LpnN9sLMy

2. Get an access_token

Replace API_KEY below with the value from the step above.

curl -k -X POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  --data-urlencode "apikey=API_KEY" \
  "https://iam.cloud.ibm.com/identity/token"

Example response

{
  "access_token": "eyJraWQiOiIyMDE5MDcyNCIsImFsZyI6IlJTMjU2In0.eyJpYW1faWQiOiJJQk1pZC0yNzAwMDdLRTNGIiwiaWQiOiJJQk1pZC0yNzAwMDdLRTNGIiwicmVhbG1pZCI6IklCTWlkIiwiaWRlbnRpZmllciI6IjI3MDAwN0tFM0YiLCJnaXZlbl9uYW1lIjoiR0VSTUFOIiwiZmFtaWx5X25hbWUiOiJBVFRBTkFTSU8gUlVJWiIsIm5hbWUiOiJHRVJNQU4gQVRUQU5BU0lPIFJVSVoiLCJlbWFpbCI6Imdlcm1hbmF0dEB1cy5pYm0uY29tIiwic3ViIjoiZ2VybWFuYXR0QHVzLmlibS5jb20iLCJhY2NvdW50Ijp7InZhbGlkIjp0cnVlLCJic3MiOiJhZWM5MTNlNmUyNDQzMWRiYzUwZmUwYTA1MWRhMmZjMSIsImltc191c2VyX2lkIjoiNzM3NjMyMSIsImltcyI6IjE3ODE5NTUifSwiaWF0IjoxNTc0ODY4MDg2LCJleHAiOjE1NzQ4NzE2ODYsImlzcyI6Imh0dHBzOi8vaWFtLmNsb3VkLmlibS5jb20vaWRlbnRpdHkiLCJncmFudF90eXBlIjoidXJuOmlibTpwYXJhbXM6b2F1dGg6Z3JhbnQtdHlwZTphcGlrZXkiLCJzY29wZSI6ImlibSBvcGVuaWQiLCJjbGllbnRfaWQiOiJkZWZhdWx0IiwiYWNyIjoxLCJhbXIiOlsicHdkIl19.ZorfH8KlEksbMyUGiQrKzFo0D4d9CIo4_yWaE6DQ3zPHWCRR3yw9q6fLdOjNUgejZkib5ek6kD6XRpQkoVW5QAisSSkkr5ldQiKCAr2PaKmJxU_o0omJpnN5SAEpRd60PZQFUrhMghsuZVDL6Mkpx5eMtRwgbyggjw6KSY09EMbZ0u2X0Nf-gslc67zCLTrdCC84RhzH6DAvd4VJvhazVSUrNaQC44h-QT64HrXaBSKoVTGZ93RgBpl3DRMljRANSCPCy_hIUa0Ux8CW4sHCFw31HX0pyOQxwPsVQi0wsD0cgZehx2qjYUor_wjL_HPGy3IWtIB5ux2dCsaoUFlwcw",
  // More information here...
}

Copy the access_token value since that will be used to authenticate subsequent requests. Look for the ACCESS_TOKEN key in the commands below.

3. Get the resource group id

Go to https://cloud.ibm.com/account/resource-groups and copy the id of the resource group to where the instance should be created.

📝 The resource group is concept is similar to the space concept in cloud foundry. It groups resources and makes it easy to handle access.

More info here: https://cloud.ibm.com/docs/resources?topic=resources-rgs

4. Get the service plan information

1. Go to https://globalcatalog.cloud.ibm.com/
2. Search for the service name like Watson Assistant.
3. Click on the arrow as shown in the GIF to select the service
4. Click on the plan name
5. Copy the ID field value

5. Create the resource instance

The create service instance endpoint requires a few input parameters.

• resource_group: obtained from the step 3. e.g 47561d9f48cc499da14961c873109e5b.
• resource_plan_id: obtained from step 4. e.g bd16e3c8-3da0-11e6-bce3-54ee7514918e.
• target: The region where the service should be created us-south, eu-gb. Check the https://cloud.ibm.com/catalog to find the regions where the service is available.

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "us-south",
    "resource_group": "47561d9f48cc499da14961c873109e5b",
    "resource_plan_id": "00495a2f-146d55dc90ad66fbc93c1315"
  }'

Example response

{
  "id": "crn:v1:bluemix:public:conversation:us-south:a/aec913e6e24431dbc50fe0a051da2fc1:4cf7415d-541b-4ab3-b923-c72f278f74e9::",
  "guid": "4cf7415d-541b-4ab3-b923-c72f278f74e9",
  "url": "/v2/resource_instances/4cf7415d-541b-4ab3-b923-c72f278f74e9",
  "created_at": "2019-11-27T16:27:12.22955299Z",
  "updated_at": "2019-11-27T16:27:12.22955299Z",
  // instance information....
}

6. Create credentials for the resource instance

The command below will create credentials for the service instance. The value for source is extracted from the guid in the previous command and identifies the service instance created above.

curl -X POST \
https://resource-controller.cloud.ibm.com/v2/resource_keys \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
  -d '{ "name": "my-instance-key-1", "source": "4cf7415d-541b-4ab3-b923-c72f278f74e9" }'

Example response

{
  "guid": "cbb0ceb6-152f-40b3-8201-1abbf854a6f9",
  "state": "active",
  "account_id": "aec913e6e24431dbc50fe0a051da2fc1",
  "resource_group_id": "47561d9f48cc499da14961c873109e5b",
  "resource_id": "7045626d-55e3-4418-be11-683a26dbc1e5",
  "credentials": {
      "apikey": "td2POPjwRRjniSCSNtiePM2txSIfaFdaa87SF6uejdot",
      "iam_apikey_name": "my-instance-key-1",
      "url": "https://gateway.watsonplatform.net/assistant/api"
  },
  // more resource key information here....
}

7. Test your service instance

Run the following command to test that Watson Assistant is working as expected.

curl -u apikey:td2POPjwRRjniSCSNtiePM2txSIfaFdaa87SF6uejdot \
https://gateway.watsonplatform.net/assistant/api/v1/workspaces?version=2019-10-10