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.

Using Authorization: Bearer token

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.

Using Authorization: ZenApiKey token

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:

  1. Log in to the web client.
  2. From the toolbar, click your avatar.
  3. Click Profile and settings.
  4. Click API key > Generate new key.
  5. Click Generate.
  6. 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 -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

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 -d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

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

curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}/v1/{method}"

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 -H "Authorization: ZenApiKey {token}" "https://{cpd_cluster_host}/v1/{method}"

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);
        }
    });

Change log

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

  • Driver APIs
  • Deployment APIs
  • Image (graphics) APIs

Related APIs

Methods

Get information about all uploaded drivers

Gets a list of database drivers.

GET /drivers

Request

No Request Parameters

This method does not accept any request parameters.

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

Response

Response Body

Driver[]

Represents a JDBC driver.

Status Code

  • 200

    A list of driver items.

  • 401

    JWTToken is missing or invalid.

Example responses
  • [
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]

Upload a driver

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: 

  • 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"

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
  • [
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]

Download information about a driver

Downloads the information of a driver.

GET /drivers/{id}

Request

Path Parameters

  • id
    Required*
    string

    Identifier of the driver.

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

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
  • [
  {
    "id": "d290f1ee6c544b0190e6d701748f0851",
    "driverFileNames": [
      {
        "filename": "db2jcc.jar",
        "fileid": "d290f1ee6c544b0190e6d701748f0852"
      }
    ],
    "driverVersion": "4.21.29",
    "targetDatabase": "db2",
    "createdAt": 86400
  }
]

Delete a driver

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.

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

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.

Download a file from a driver

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.

  • 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}'

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.

Get information about all deployment files

Gets a list of deployments.

GET /deployments

Request

No Request Parameters

This method does not accept any request parameters.

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

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.

Upload a deployment file

Uploads a deployment zip file.

POST /deployments

Request

Form Parameters

  • fileName
    Required*
    binary
  • 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}"

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.

Download a deployment file

Downloads a deployment file.

GET /deployments/{id}

Request

Path Parameters

  • id
    Required*
    string

    Identifier of the deployment to download.

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

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.

Delete a deployment file

Deletes a deployment file.

DELETE /deployments/{id}

Request

Path Parameters

  • id
    Required*
    string

    Identifier of the deployment file to delete.

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

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.

Get information about all image files

Gets a list of image metadata.

GET /images

Request

No Request Parameters

This method does not accept any request parameters.

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

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.

Upload a list of images

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

  • 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"

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.

Download an image

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.

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

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.

Delete an image

Deletes an image file.

DELETE /images/{imageId}

Request

Path Parameters

  • imageId
    Required*
    string

    File path of the image to delete in the images directory.

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

Response

Status Code

  • 204

    Image 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.