Db2 on Cloud API documentation improvements #131
Description
Which topic are you reporting about?
https://cloud.ibm.com/apidocs/db2-on-cloud/db2-on-cloud-v4
What do you think needs to be updated?
Suggestions for improvement to Db2 on Cloud API documentation:
Based on recent client feedback from CS4084019 and CS4100241 tickets, I suggest adding the below improvements to the Db2 on Cloud API documentation. Please reach out to me via email ([email protected]) or Slack (@jepstein) to discuss this further, should you need additional context.
Suggestion 1)
More clearly mention the need to URL-encode the x-deployment-id value (i.e. the CRN associated with the database).
I see this requirement is stated in the initial documentation on specifying deploymentID as part of the request header
https://cloud.ibm.com/apidocs/db2-on-cloud/db2-on-cloud-v4#security-scheme-deploymentId
deploymentId
The deployment id of the service, which can be obtained after provision. When providing the deployment id in the header, use URL encoding. For example, ":" should be escaped as "%3A", and "/" should be escaped as "%2F".
However, many customers do not read the documentation cover to cover and instead only refer to the documentation for the API call in question. The example API calls (see below) do not specify this requirement.
curl -X POST https://{REST_API_HOSTNAME}/dbapi/v4/backups/restore -H 'accept: application/json' -H 'authorization: Bearer {AUTH_TOKEN}' -H 'content-type: application/json' -H 'x-deployment-id: {DEPLOYMENT_ID}' -d '{"ts":"<ADD STRING VALUE>","backup_id":"crn:v1:ibm:local:database:us-south:a/c5555555580015ebfde430a819fa4bb3:console-dev01:backup:ac9555b1-df50-4ecb-88ef-34b650eff712"}'
I think a better way to avoid confusion around this would be to specify the requirement in the {DEPLOYMENT_ID}, for example:
curl -X POST https://{REST_API_HOSTNAME}/dbapi/v4/backups/restore -H 'accept: application/json' -H 'authorization: Bearer {AUTH_TOKEN}' -H 'content-type: application/json' -H 'x-deployment-id: {URL-encoded CRN}' -d '{"ts":"<ADD STRING VALUE>","backup_id":"crn:v1:ibm:local:database:us-south:a/c5555555580015ebfde430a819fa4bb3:console-dev01:backup:ac9555b1-df50-4ecb-88ef-34b650eff712"}'
Suggestion 2)
Related to the above, the x-deployment-id documentation (https://cloud.ibm.com/apidocs/db2-on-cloud/db2-on-cloud-v4#security-scheme-deploymentId) should more explicitly state the deploymentID is the CRN associated with the database instance and link to the Db2 on Cloud documentation on how to locate the CRN and database credentials (see below link).
https://cloud.ibm.com/docs/Db2onCloud?topic=Db2onCloud-db_details_cxn_creds#location
Suggestion 3)
More clearly state the userID in the authentication call POST /dbapi/v4/auth/tokens (ref: https://cloud.ibm.com/apidocs/db2-on-cloud/db2-on-cloud-v4#authenticate) needs to be an IAM-provisioned user not a JDBC (database-level) user. This may seem obvious to those within IBM Cloud but this is a frequent source of confusion for customers.
Suggestion 4)
Documentation should specify where to find the REST_API_HOSTNAME value in the web console, i.e. under the Administration > Connections tab in the web console (see attached screenshot)
Suggestion 5)
Multiple occurrences of brackets { } in the example API calls (some of which are placeholders, others of which are required components of JSON object of header values) are confusing.
For example in the below example from GET /dbapi/v4/backups/ (https://cloud.ibm.com/apidocs/db2-on-cloud/db2-on-cloud-v4#getbackups):
curl -X GET https://{REST_API_HOSTNAME}/dbapi/v4/backups -H 'accept: application/json' -H 'authorization: Bearer {AUTH_TOKEN}' -H 'content-type: application/json' -H 'x-deployment-id: {DEPLOYMENT_ID}'
The following are placeholders, meaning the { } should be removed once the relevant substitution is made:
{REST_API_HOSTNAME}{AUTH_TOKEN}
While the brackets in {DEPLOYMENT_ID} are a required component of the JSON object passed as value of the x-deployment-id header.
One potential solution is to revise the syntax to use $ to indicated placeholder variables and { } only when the brackets need to be included with the object, such as in the JSON object passed as value of the x-deployment-id header.
Using the above example, the revised syntax would look like the below:
curl -X GET https://$REST_API_HOSTNAME/dbapi/v4/backups -H 'accept: application/json' -H 'authorization: Bearer $AUTH_TOKEN' -H 'content-type: application/json' -H 'x-deployment-id: {$DEPLOYMENT_ID}'
Anything else?
No response