Authentication
Before using the REST APIs, your client application must authenticate to the Cognos Analytics server by issuing a PUT https://<cognos_analytics_server>/api/v1/session
request with credentials specified in the body object. For example:
{
"parameters": [
{
"name": "CAMNamespace",
"value": "LDAP"
},
{
"name": "CAMUsername",
"value": "johnsmith"
},
{
"name": "CAMPassword",
"value": "mypassword"
}
]
}
Note: Parameter name-value pairs are case-sensitive.
Depending on the authentication provider you are using, the /session endpoint may not allow you to authenticate with a password. In this case, you will need to use an API login key:
"parameters": [
{
"name" : "CAMAPILoginKey",
"value" :"yourapikey"
}
]
}
Lastly, you can optionally use the APIs with anonymous login by issuing a GET https://<cognos_analytics_server>/api/v1/session
request.
The base URL for all endpoints is api/v1
. For example, to GET a list of imported files using the /files
endpoint, you can issue the following request:
https://<cognos_analytics_server>/api/v1/files
or update your data modules by issuing a PUT command to:
https://<cognos_analytics_server>/api/v1/modules/{moduleid}
REST clients must send an X-XSRF-Token request header on all requests except session creation. Set the value to the value returned in the XSRF-Token cookie. You can obtain an XSRF-Token cookie by issuing a GET request to /api/v1/session
. For example:
curl -b cookie.txt -k -H "x-xsrf-token: ${xsrf}" "https://my.caserver:9300/api/v1/content"
where -b
sends the cookies. You can optionally use the -c
option to generate a cookie.txtfile
. Including both options sends the cookies and saves any new ones that are returned.
Requests cannot be sent to the external gateway (IIS or Apache); otherwise, an extra rewrite rule would be required to handle /api
requests.
Using session_key
To avoid using cookies, use the following example to create a session:
-d "{\"parameters\":[{\"name\": \"CAMNamespace\",\"value\": \"LDAP\"},
{\"name\": \"CAMUsername\",\"value\": \"johnsmith\"},
{\"name\": \"CAMPassword\",\"value\": \"mypassword\"}]}"
"http://caserver:9300/api/v1/session"
The JSON response resembles the following:
"generation": 3,
"shareable": false,
"isAnonymous": false,
"cafContextId": "CAFW000000a0Q0FGQTYwMDAwMDAwMDlBaFFBQUFCcmJZZXFnWVdHcWFsa0x2U2RSbWVYeEt4WWZnY0FBQUJUU0VFdE1qVTJJQUFBQUxnS1BGWXUxb1BBYThBRDJTdGVOTUg4R1lySHJ6WE5CcmwwT2ZwR0gxQ2I0NDgzODR8cnM_",
"logEnabled": false,
"canCallLogon": true,
"url": "/api/v1",
"session_key": "CAM MTsxMDE6OTZlNjI5YzctNzE1OC0wODQ0LWRkYTgtNjY3ZTQ5ZGQ5ZDE0OjEzMDY0NjI5NzY7MDszOzE7"
}
You can then use the session_key
value in all subsequent requests by sending it in a request header. For example:
"IBM-BA-Authorization: CAM MTsxMDE6OTZlNjI5YzctNzE1OC0wODQ0LWRkYTgtNjY3ZTQ5ZGQ5ZDE0OjEzMDY0NjI5NzY7MDszOzE7"
"http://caserver:9300/api/v1/content"