Introduction

AIP Console has API documentation provided by Swagger. This documentation is interactive and you can test requests directly. The API documentation is accessible via the following URL (change the URL to suit your own environment):

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

Click to enlarge

The AIP Console API interface contains API commands for both the AIP Console and AIP Node(s).

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

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 AIP 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:

List of available "jobs"

Job type

Description

analyze Run analysis for a specific version of an application
reject_version Reject a version of an application
delete_version Delete a version of an application
purge_version Purge a version of an application
delete_snapshot Delete a snapshot of an application
upload_applicationUpload application to measurement service
consolidate_snapshotConsolidate a snapshot
declare_applicationCreate an application
delete_application Delete an application
function_pointsCompute function points
deliver_version Create and deliver a version for an application
BACKUPbackup the triplet and the delivery folder for an application
backup_measurementbackup measurement schema
RESTORErestore an application to a previous state based on a backup
SHERLOCK_BACKUP Create a Sherlock backup
upload_deliver_version Unzip previously uploaded source and deliver version
upload_snapshot_version Unzip previously uploaded source, create version, analyze and create a snapshot
rescan_applicationClone previous version, launch analysis and create a snapshot
add_version Add a new version for an application
clone_version Clone an existing version's structure
edit_version Edit an existing version
sync_application Synchronize application
dataflow_security_analyze Run dataflow security analyzer

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:

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

StatusDescription
completedJob is done successfully
startedJob is in progress
startingJob is in pending state waiting for execution
stoppedJob was interrupted in the middle of the process
failedJob completed with failure
cancelledJob is cancelled by user

Real life implementation of the API

CAST has used the AIP 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.

Note:

  • If you are a member of the CAST-Extend GitHub organization, you can push merge requests from another branch (master branch is read-only) or you can fork the project and change it to suit your own requirements
  • These tools are not supported by CAST