Using the Analytics Results (OData) API

General Points

In this part of the documentation, we will use the words ”Analytics Results service” to refer to the base address of the OData service. For the Management and Orchestration platform, this URL can be found on the /cxarm/cxanalytics path, relative to the platform hostname (http://<host name>:<port>/cxarm/cxanalytics).

Unless stated otherwise, all addresses in the rest of this documentation are relative to the Analytics Results service, apart from when requesting an access token for authentication.

Versioning and Media Type

Management and Orchestration is installed with the latest version (i.e. v=1.0) of the Analytics Results (OData) API. In order to use another version of the Analytics Results (OData) API you will need to add ';v=<version>' to a media type header in the request.

The media type header defined will depend on the request being used:

• GET Request – Accept: application/json;v=1.0
• POST, PUT, PATCH and DELETE Requests – Content-Type: json;v=1.0

Methods

The Analytics Results service is currently read-only, therefore apart from the authentication method where POST is used, GET is the only method allowed.

Metadata

The metadata document is located on /$metadata. This document contains a complete description of the feeds, entity types, properties, entity sets and relationships exposed by the Analytics Results service. An example of the actual data structure exposed can be seen in the Catalog section, below.

Format

The Analytics Results service supports XML format.

Catalog

The $metadata document displays the catalog of all data available through the Analytics Results service. For an example, see http://localhost:8080/cxarm/cxanalytics/$metadata

Paging

Client-driven paging can be requested with the $top query parameter to limit the size of the response, and the $skip query parameter to define the first result to display. The server will ignore $skip results and then return the first $top items.

When paging is applied, a link to the next results will be added at the end of the payload.

Restriction

The $filter parameter can be used to apply a restriction on results.

Supported restriction operators are eq and ne for equality and inequality, lt and gt for strict inequalities (less than and greater than) and le and ge for non-strict inequalities (less than or equal and greater than or equal).

Multiple restriction expressions can be combined into bigger expressions with the logical operators and and or.

Expressions can be negated with the not operator.

Count

Using the $count query parameter, there are 2 ways of obtaining the number of results from the Analytics Results service.

These two methods provide slightly different results:

• The first one returns the count relative to the payload, taking all operations into account, and is returned along with the payload.
• The second one returns the absolute resource count, irrespective of anything other than the number of records present on the server and only returns the number, without any other information.

Expand

The Analytics Results service supports nested filters in $expand.

Sort

Results returned by the Analytics Results service can be sorted using the $orderby parameter. The field name can be followed by the asc and desc keywords to specify the sort order (default is ascendant).

Specific record

To access a specific record, its record id surrounded by apostrophes 'xx', can be added to the request.

Projection

Results can be projected over specific fields using the $select parameter.

For multiple fields to be subject of the projection, their names must be separated by a comma and an optional space. This parameter can be used with sets of data and for specific records.

Testing

We will use authentication and request submission in Postman for most of the API testing examples.

Authentication

An authenticated user can be granted access to restricted sets of data and benefit from extended quotas for API calls. The Analytics Results (OData) API features an authentication mechanism for users to be granted their specific authorizations.

To complete the authentication procedure you need to know the following basic fundamentals:

• The basics of using REST APIs, e.g. requests, responses, headers
• The basics of using Checkmarx Management and Orchestration

We will use access token-based authentication in Postman for this example.

Step 1: Requesting an access token for authentication

You need to receive an access token for authentication. The first thing you need to do is make a request to the authentication server by including the credentials received from the authorization server.

To do this, just submit (POST) the desired credentials to the token endpoint using the Content-Type: application/x-www-form-urlencoded format in the request body:

• Endpoint example: http://<server-name/ip>:<port>/cxrestapi/auth/identity/connect/token
• Credentials example:
  • username: <Cx username>
  • password: <Cx password>
  • grant_type: Value must be set as 'password'
    
  • scope: Value must be set as:
    • ‘cxarm_api’ for v8.8.0 and v8.9.0
    •  ‘management_and_orchestration_api’ and ‘sast_api’ for v9.0.0 and up
  • client_id: Value must be set as:
    • ‘resource_owner_client’ for v8.8.0 and v8.9.0
    • ‘management_and_orchestration_server’ for v9.0.0 and up
  • client_secret: Value must be set as '014DF517-39D1-4453-B7B3-9930C563627C'

The access token request will look some similar to the following:

Create Access Token v8.8.0 and v8.9.0:
curl --location --request POST 'https://cx-sast.cx.local/cxrestapi/auth/identity/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=****' \
--data-urlencode 'password=********' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=sast_rest_api' \
--data-urlencode 'client_id=resource_owner_client' \
--data-urlencode 'client_secret=014DF517-39D1-4453-B7B3-9930C563627C'

This creates a login session and returns the requested access token response information, which will look similar to the following:

If the access token request is valid and authorized, the authorization server issues an access token response.

An example successful access token response:

   {
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGtr0hoV4Vj8GNkyk2A…………..",
      "expires_in": 3600,
      "token_type": "Bearer"
    }  

If the request failed client authentication or is invalid, the authentication server returns an access token error response.

An example access token error response:

   {
      "error":"invalid_grant"
    }

This error means that the provided authorization grant is invalid, expired, revoked or issued to another client. For more examples of errors with responses, see the Error Responses.

Step 2: Using the access token in a request to the resource server

When you want to make a request to the resource server you should send the access token (access_token) received during authentication.

To do this, just submit (GET) the access token value to the resource in the request header:

• Resource example: http://<server-name/ip>:<port>/cxarm/cxanalytics/Projects
• Credentials example:
  • uthorization: Bearer <access token value>
  • Accept: application/json;v=1.0

The session request will look some similar to the following:

Now, when you submit the request, this access token value is used for authentication, until the token expires.

Authentication Errors

The following errors may occur during authentication:

Token Expiration

If you have not used the Analytics Results (OData) API for a while, you need to perform the authentication again because your token has expired. You will receive an error response. The response body will contain a message telling you that your token is invalid. At this point, you will need to re-authenticate using the access token request procedure in the Analytics Results (OData) API.