Getting started with the REST API

To interact with the IBM® Cognos® Analytics REST API, your client application must perform these tasks:

authenticate to the Cognos Analytics server
send an X-XSRF-Token request header on all requests except session creation
use a session key to create a session

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"
     }
]
 }

Last, 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}

Headers

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"