AIP Console - Interactive API documentation

Introduction

Console has a built in RestAPI that can be used for automation purposes - interactive documentation is available and allows you to test requests directly. The API documentation is accessible via the following URL (change the URL to suit your own environment):

http://<console>:8081/swagger-ui.html

Click to enlarge

Authorization

Before you can interactively use the graphical API, you must be authorized. Authorization requires a user API key, which you can generated in your user profile settings:

Using the API interactively

Show the request type you want to test:

Expand the specific request using the blue section in the top left:

and click Try it out:

Click to enlarge

Job parameters

See AIP Console - Interactive API documentation - Job Parameters for more information.

Using curl to interact with the API - request headers

It is possible to interact with the API using curl, in which case, as well as an API key, you will also need to use a CSRF token, for example:

curl --location --request GET 'http://localhost:8081/api/applications' \
--header 'x-api-key: qZUfQfX3.G5Yx7ehS2HI9Va5k4h0uTM7jbF0YWT9R' \
--header 'x-xsrf-token: e01b177c-f5d1-4137-a9c3-8ef39bef67e6'

To generate a CSRF token, run a GET request to /api/:

curl --location --request GET "http://host:port/api/"

And then retrieve the token from cookies:

How to schedule a "job" with the API

The /job API is the main API in Console and is used to launch actions such as create application, add version, launch analysis etc. The basic flow of consuming the /jobs API is:

• Schedule a job with a job type
• Poll the job details API to get the real-time job status

List of available "jobs"

Getting the request payload

Depending on the job type, the request payload for each job is different, therefore the easiest way to get the exact payload is to run a test using your browser's dev tools:

• F12 to open the dev tools of Chrome (for example) and launch the action in Console
• In dev tools, switch to the Network tab
• Click on the POST request to /jobs and then click the Headers tab
• Check the request payload

Use case

Example to add a version of a given application and generate a snapshot. POST /jobs to schedule a job with type add_version, using an existing predefined source folder: source.folder.location: webi/source_code

curl --location --request POST 'http://host:port/api/jobs' \
--header 'x-api-key: 87IUS4TO.9SzUy5om67lkhlcRQJzppf3ltRFhDcUo' \
--header 'x-xsrf-token: 4d1620ac-dbfd-4ffa-ac56-e14fa9bd88da' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jobType": "add_version",
    "jobParameters": {
        "endStep": "consolidate_snapshot",
        "versionName": "Version-2020-04-27T14-29-55",
        "appGuid": "225e7c73-2dbd-486d-a1df-53d66f39ff75",
        "appName": "spag2",
        "deliveryConfigGuid": "",
        "releaseDate": "2020-04-27T12:29:55.987Z",
        "sourcePath": "sources:webi/source_code",
        "fromVersionGuid": "3b5cdb3a-eb64-4d63-b38c-25454282b495",
        "extensionAutoConfigEnabled": true,
        "objectives": "global_risk,functional_points",
        "moduleGenerationType": "one_per_techno"
    }
}'

In the response of the api, we get a "jobUrl" url which gives realtime status of the job:

{
    "appGuid": "225e7c73-2dbd-486d-a1df-53d66f39ff75",
    "jobGuid": "c784880e-377a-4dc3-a6f5-6a63d5866bf2",
    "jobUrl": "/api/jobs/c784880e-377a-4dc3-a6f5-6a63d5866bf2"
}

Poll the jobUrl to get the realtime status:

curl --location --request GET 'http://host:port/api/jobs/c784880e-377a-4dc3-a6f5-6a63d5866bf2' \
--header 'x-api-key: 87IUS4TO.9SzUy5om67lkhlcRQJzppf3ltRFhDcUo' \
--header 'x-xsrf-token: 4d1620ac-dbfd-4ffa-ac56-e14fa9bd88da' \

Job status shows in the response with the current step:

{
	"progressStep": "code_scanner"
	"state": "started"
	"updated": "2020-04-27T13:08:34.662Z"
	"url": "/api/jobs/0c84c2ad-765e-4865-9598-30112ac81dd3"
}

Job status

Real life implementation of the API

CAST has used the Console API to build various tools that can be used to improve the analysis process (Jenkins plugin and automation). You can find out more about these tools here: https://github.com/CAST-Extend/com.castsoftware.uc.aip.console.tools - explore tools to see how the API can be used in a real life context.