- 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.
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
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.
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
- Go to
https://globalcatalog.cloud.ibm.com/
- Search for the service name like Watson Assistant.
- Click on the arrow as shown in the GIF to select the service
- Click on the plan name
- Copy the ID field value
The create service instance endpoint requires a few input parameters.
resource_group
: obtained from the step 3. e.g47561d9f48cc499da14961c873109e5b
.resource_plan_id
: obtained from step 4. e.gbd16e3c8-3da0-11e6-bce3-54ee7514918e
.target
: The region where the service should be createdus-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....
}
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....
}
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