Cognos Analytics Artifacts API | IBM Cloud API Docs

Create and manage Cognos Analytics JDBC Drivers, deployments and images on IBM® Cloud Pak for Data by using the Cognos Analytics Artifacts REST API.

Introduction

The Cognos Analytics Artifacts API is used to create and maintain artifacts that can be used to access databases through JDBC, deployments that can be imported or exported, plus images that can be displayed in reports and dashboards.

Endpoint URLs

The service endpoint is based on your IBM Cloud Pak deployment URL.

https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/{method}

For example, if your instance is deployed at https://www.example.com:31843, you can access the APIs at https://www.example.com:31843/cognosanalytics/{tethered_namespace}/artifacts/v1/{method}.

Example request to endpoint

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/{method}"

Replace {token}, {request_method}, {tethered_namespace} and {method} in this example with the values for you particular API call.

Authentication

To authenticate to the API, pass a bearer access token or platform API key token in an Authorization header.

If Identity and Access Management (IAM) are not enabled, you can generate a token by using your username and password against the Get authorization token endpoint.

If IAM is enabled, you can generate a token by using your username and password against the /idprovider/v1/auth/identitytoken endpoint.

With a platform API key, you can access everything that you would typically be able to access when you log in to the Cloud Pak for Data web client.

To generate a platform API key through the user experience:

Log in to the web client.
From the toolbar, click your avatar.
Click Profile and settings.
Click API key > Generate new key.
Click Generate.
Click Copy and save your key somewhere safe. You cannot recover this key if you lose it.

Alternatively, you can call the Generate API key method. Note: this method must be called with bearer access token authorization.

When you get the API Key from the user experience or from the generate API Key method, you must base64 encode <username>:<api_key> to get the token.

Generating an access token by using the Get authorization token endpoint. The response includes a token property.

Replace {cpd_cluster_host} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -X POST "https://{cpd_cluster_host}/icp4d-api/v1/authorize" -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" -H "Content-Type: application/json"

Copy to clipboard

Alternatively, you can use an API key instead of a password. Replace {username} and {api_key} with your IBM Cloud Pak for Data credentials.

curl -k -X POST "https://{cpd_cluster_host}/icp4d-api/v1/authorize" -d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" -H "Content-Type: application/json"
Copy to clipboard

Authenticating to the API by using an access token. Replace {token} with your details.

curl  "https://{cpd_cluster_host}/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"
Copy to clipboard

Authenticating to the API by using a base64 encoded API key token. Replace {token} with your details.

Generate the token by using an API key and its respective username.

echo "<username>:<api_key>" | base64

curl "https://{cpd_cluster_host}/v1/{method}" -H "Authorization: ZenApiKey {token}" -H "Content-Type: application/json"
Copy to clipboard

Error handling

Required Purpose: Defines common response codes and the language-specific response models. For more information, see API Handbook - Errors. Example:

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Table 1. Error codes
HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`500`	Internal Server Error	offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

ErrorResponse

Table 2. A caption for the table
Name	Type	Description
`status`	Integer	HTTP error code.
`error`	String	Human-readable error string, like 'Invalid image file'.

When the Node SDK receives an error response from the Visual Recognition service, it creates an Error object with information describing the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table:

Errors

Table 6. A caption for the table
Error Field	Description
status	The HTTP status code returned
error	A message describing the error

artifacts.method(params,
    function(err, response) {
        // The error will be the first argument of the callback
        if (err.status == 404) {
            // Handle Not Found (404) error
        } else if (err.status == 413) {
            // Handle Request Too Large (413) error
        } else {
            console.log('Unexpected error: ', err.code);
            console.log('error:', err);
        }
    });
Copy to clipboard

Change log

The Cognos Analytics Artifacts API now includes the following methods and examples:

Driver APIs
Deployment APIs
Image (graphics) APIs

IBM Cloud Pak for Data

Gets a list of database drivers.

GET /drivers

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/drivers' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

Driver[]

Represents a JDBC driver.

Status Code

200
A list of driver items.
401
JWTToken is missing or invalid.

Example responses

Status 200

[
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]
Copy to clipboard

Adds a JDBC driver. If the driver consists of multiple files, upload all required files in a single request.

POST /drivers

Request

Form Parameters

files
Required*
[]
The driver files to upload. Multiple files can be uploaded.
driverVersion
string
Driver version.

Default: 1.0
targetDatabase
string
Text description for the database intended to use this driver.

Default:

Example request

curl -k -X POST 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/drivers' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -F "files=@./drivers/in/db2jcc.jar"
Copy to clipboard

Response

Response Body

Driver

Represents a JDBC driver.

Status Code

201
Driver file uploaded successfully.
400
An error occurred, see response for details.
401
JWTToken is missing or invalid.
409
This object already exists.

Example responses

Status 201

[
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]
Copy to clipboard

Downloads the information of a driver.

GET /drivers/{id}

Request

Path Parameters

id
Required*
string
Identifier of the driver.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/drivers/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

Driver

Represents a JDBC driver.

Status Code

200
Driver information returned successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

Example responses

Status 200

[
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]
Copy to clipboard

Deletes a driver. Any additional files that were uploaded will be also deleted.

DELETE /drivers/{id}

Request

Path Parameters

id
Required*
string
Identifier of driver to delete.

Example request

curl -k -X DELETE 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/drivers/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Status Code

204
Driver deleted successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

No Sample Response

This method does not specify any sample responses.

Downloads driver files.

GET /drivers/{id}/filenames/{fileid}

Request

Custom Headers

Accept
string
Allowable values: [application/zip,application/jar]

Path Parameters

id
Required*
string
Identifier of the driver.
fileid
Required*
string
Identifier of the driver file.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/drivers/d290f1ee6c544b0190e6d701748f0851/filenames/abc0f1ee6c544b0190e6d701748f0852' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

binary

Status Code

200
Driver file returned successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

No Sample Response

This method does not specify any sample responses.

Gets a list of deployments.

GET /deployments

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/deployments' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

Deployment[]

Represents a deployment file.

Status Code

200
List of deployment files.
401
JWTToken is missing or invalid.

No Sample Response

This method does not specify any sample responses.

Uploads a deployment zip file.

POST /deployments

Request

Form Parameters

fileName
Required*
binary

Example request

curl -k -X POST 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/deployments' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -F "fileName=@{deployment.zip}"
Copy to clipboard

Response

Response Body

Deployment

Represents a deployment file.

Status Code

201
Deployment file uploaded successfully.
400
An error occurred, see response for details.
401
JWTToken is missing or invalid.
409
This object already exists.

No Sample Response

This method does not specify any sample responses.

Downloads a deployment file.

GET /deployments/{id}

Request

Path Parameters

id
Required*
string
Identifier of the deployment to download.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/deployments/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

binary

Status Code

200
Deployment file returned successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

No Sample Response

This method does not specify any sample responses.

Deletes a deployment file.

DELETE /deployments/{id}

Request

Path Parameters

id
Required*
string
Identifier of the deployment file to delete.

Example request

curl -k -X DELETE 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/deployments/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Status Code

204
Deployment file deleted successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

No Sample Response

This method does not specify any sample responses.

Gets a list of image metadata.

GET /images

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/images' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

Images[]

Represents an image.

Status Code

200
List of image metadata.
401
JWTToken is missing or invalid.

No Sample Response

This method does not specify any sample responses.

Uploads a list of images.

POST /images

Request

Form Parameters

files
Required*
[]
The image files to upload. Multiple images can be uploaded.
dirpath
string
The directory to save images in under 'webcontent/bi/customImages'. By default, the directory will be '/opt/ibm/cognos/analytics'.

Default: /opt/ibm/cognos/analytics/webcontent/bi/
tolerance
string
The action to take for a duplicate file name. The default value is skip.

Allowable values: [skip,overwrite,fail]
Default: skip

Example request

curl -k -X POST 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/images' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -F "files=@./images/sample_gif.gif" -F "dirpath=gifdir"
Copy to clipboard

Response

Response Body

Images

Represents an image.

Status Code

200
Images uploaded successfully.
401
JWTToken is missing or invalid.
406
Use a valid image with .jpg, .jpeg, .png, .gif, or .svg extension.
409
This object already exists.

No Sample Response

This method does not specify any sample responses.

Downloads an image.

GET /images/{imageId}

Request

Custom Headers

Accept
string
Allowable values: [image/png,image/jpg,image/gif,image/svg]

Path Parameters

imageId
Required*
string
Identifier of the image to download.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/images/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Response

Response Body

binary

Status Code

200
Image returned successfully.
401
JWTToken is missing or invalid.
404
The object cannot be found.

No Sample Response

This method does not specify any sample responses.

Deletes an image file.

DELETE /images/{imageId}

Request

Path Parameters

imageId
Required*
string
File path of the image to delete in the images directory.

Example request

curl -k -X DELETE 'https://{cpd_cluster_host}/cognosanalytics/{tethered_namespace}/artifacts/v1/images/d290f1ee6c544b0190e6d701748f0851' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Copy to clipboard

Introduction

Endpoint URLs

Authentication

Error handling

ErrorResponse

Errors

Change log

Related APIs

Methods

Get information about all uploaded drivers

Request

No Request Parameters

Response

Response Body

id

driverFileNames

filename

fileid

driverVersion

targetDatabase

createdAt

Status Code

200

401

Upload a driver

Request

Form Parameters

files

driverVersion

targetDatabase

Response

Response Body

id

driverFileNames

filename

fileid

driverVersion

targetDatabase

createdAt

Status Code

201

400

401

409

Download information about a driver

Request

Path Parameters

id

Response

Response Body

id

driverFileNames

filename

fileid

driverVersion

targetDatabase

createdAt

Status Code

200

401

404

Delete a driver

Request

Path Parameters

id

Response

Status Code

204

401

404

No Sample Response

Download a file from a driver

Request

Custom Headers

Accept

Path Parameters

id

fileid

Response

Response Body