Skip to main content

CloudScend Foresight API Guide

CloudScend Foresight API Guide

Introduction​

The CloudScend Foresight API provides access to endpoints you can use to integrate into your own tools.

The most important endpoints of the CloudScend Foresight API have been organized below into feature areas.

Base URL​

All URLs referenced in the documentation start with a base URL variable which represents the protocol and host name of the applicable CloudScend Foresight API service. For example https://foresight-api-backend.example.com.

The default baseURL variable should point to the CloudScend Foresight backend API service. sourceCodeUploaderBaseUrl should point to the CloudScend Foresight Source Code Uploader API service.

Authentication​

All endpoints require authentication and are secured using Keycloak. CloudScend Foresight uses OAuth2 for authentication and authorization of the API. OAuth2 is a protocol designed to let third-party applications authenticate to perform actions as a user, without getting the user's password. There are several libraries available that implement the protocol, and a good list can be found at the OAuth2 home page. Through the use of OAuth2, you'll go through the process of obtaining a token and then you'll use that token in every request made to the CloudScend Foresight API to verify your identity.

CloudScend Foresight API servers accept Bearer tokens through the HTTP Authorization header in requests. Bearer tokens allow requests to authenticate using an access key, such as a JSON Web Token (JWT).

The example below shows how to automate processes by requesting a token from Keycloak, extracting the token, and passing the token to the CloudScend Foresight backend, which would be suitable for a CI/CD pipeline.

#!/bin/bash

echo "Requesting authentication"

RESULT=`curl -s --location --request POST \
"$KEYCLOAK_BASE_URL/auth/realms/appmod/protocol/openid-connect/token" \
--data-urlencode 'grant_type=password' \
--data-urlencode "username=$FORESIGHT_USERNAME" \
--data-urlencode "password=$FORESIGHT_PASSWORD" \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=sage'`
echo $RESULT

TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`
echo "Extracted token"
echo $TOKEN

curl $FORESIGHT_API_BASE_URL/sage/application/ -H "Authorization: bearer $TOKEN"

Postman Collection​

The quickest way to get started is to use our Postman request collection. The following steps will help you get up and running.

  1. Import the CloudScend Foresight Postman Collection

  2. Configure Postman Environment

    • Setup a new environment in Postman. Click New -> Environment.
    • Name the new environment Foresight API
    • Add the following variables:
      • baseUrl: enter the CloudScend Foresight Backend API URL
      • sourceCodeUploaderBaseUrl: enter the CloudScend Foresight Source Code Uploader Base URL
      • loginBaseUrl: enter the Keycloak service base url
    • Click Add to create

  3. Authenticate

    • In the Authorization tab for the collection, select OAuth 2.0 from the Type dropdown list. By default Postman will append the access token to Bearer in the Authorization header for your request.
    • To request an access token, fill out the fields in the Configure New Token section. There are several ways to configure based on the Grant Type you want to use. For the Password Credentials grant type enter the following details:
      • Access Token URL: {{loginBaseUrl}}/auth/realms/appmod/protocol/openid-connect/token
      • Client ID: sage
      • Username: {{FORESIGHT_USERNAME}}
      • Password: {{FORESIGHT_PASSWORD}}
      • Scope: openid email profile
      • Client Authentication: Send as Basic Auth header
    • Click Get New Access Token
    • Click Use Token
    • Click Update to save the Authorization details. You can save both the token and the details to generate a token with your request or collection.
    • View Postman Documentation on OAuth2 Authentication for more info.

  4. Explore the API

    • Execute any of the requests within the collection
    • Refer to this documentation for the requirements of each request

Application​

This collection describes the important endpoints for working with Applications. Before doing any analysis in CloudScend Foresight you must first create an Application.

Get Applications​

GET{{baseUrl}}/sage/application/

Retrieves a list of applications the user has access to.

Example Response​

[
  {
    "id": -83970435,
    "applicationId": "voluptate nostrud pariatur veniam adipisicing",
    "applicationName": "dolor sit nisi",
    "applicationUser": "dolore",
    "projectManager": "elit incididunt mollit",
    "functional": "ea commodo Ut ullamco",
    "applicationLanguage": "TSQL",
    "analysisStatus": "CODE_ANALYSIS_ERROR",
    "artifactUrl": "enim in tempor eu dolor",
    "appOwner": "dolor proident ut",
    "surveyStatus": "laboris pariatu",
    "cestatus": "CE_NOT_ATTEMPTED",
    "programManager": "laborum et fugiat"
  },
  {
    "id": -92365495,
    "applicationId": "voluptate commodo velit",
    "applicationName": "elit eiusmod esse",
    "applicationUser": "in",
    "projectManager": "Excepteur adipisicing Ut",
    "functional": "officia in",
    "applicationLanguage": "TYPESCRIPT",
    "analysisStatus": "CODE_ANALYSIS_PROGRESS",
    "artifactUrl": "eiusmod elit officia",
    "appOwner": "lab",
    "surveyStatus": "laborum eu in consectetur",
    "cestatus": "CE_READY_WITH_NO_REPORT",
    "programManager": "ut incididunt labore est Ut"
  }
]

Get Application History​

GET{{baseUrl}}/sage/appHistoryList/:app-id

Retrieves a list of application versions including the version tag and source code upload timestamp. A new application version is created each time source code is uploaded.

Path variables​
KeyTypeDescription
app-idstring(Required)

Example Response​

[
  {
    "appGlobalId": "tempor aliquip occaecat nulla ipsum",
    "id": 38868107,
    "gitTag": "mollit cillum",
    "uploadTimestamp": "1978-12-24T07:54:29.663Z"
  },
  {
    "appGlobalId": "sed dolor exercitation",
    "id": 44339925,
    "gitTag": "Excepteur",
    "uploadTimestamp": "1949-08-13T12:25:44.757Z"
  }
]

Source Code​

Upload Source Code for an Application​

POST{{sourceCodeUploaderBaseUrl}}/pupload/:appGlobalId

Stores a zip file containing an application's source code. Upon successful upload, check the status of processing the zip file contents using the Get Code Analysis Status endpoint.

Path variables​
KeyTypeDescription
appGlobalIdApplication Id (Required)

Example Response​

{ "id": "0000-0000-0000-0000", "success": true, "message": "good to go" }

Get Code Analysis Status​

GET{{baseUrl}}/sage/app-analysis/status/:appGlobalId

Returns the current source code analysis status for the latest source code version of an application.

CodeStatusMeaning
READY_FOR_CODE_UPLOADReady for source code uploadNo source code has been uploaded for the application yet
CODE_UPLOADEDSource code uploadedSource code has been successfully uploaded but analysis has not started yet
CODE_UPLOAD_ERRORError uploading source codeAn error occurred extracting the source code from the uploaded source code zip file
CODE_ANALYSIS_PROGRESSAnalysis in progressSource code analysis is in progress
CODE_ANALYSIS_DONEAnalysis results readySource code analysis is complete
CODE_ANALYSIS_ERRORSource code analysis errorSource code analysis failed processing.
Path variables​
KeyTypeDescription
appGlobalIdstring(Required)

Example Response​

{
  "appGlobalId": "ce791988-8161-4369-b744-57eb77311ef7",
  "status": "CODE_ANALYSIS_ERROR"
}

Reports​

Get analysis reports for application and tag​

GET{{baseUrl}}/sage/reports/history/:app-id/:git-tag

Retrieves the analysis reports data for a given application and version (tag).

Path variables​
KeyTypeDescription
app-idstring(Required)
git-tag(Required)

Example Response​

[
  {
    "applicationId": "<string>",
    "reportName": "<string>",
    "s3Uri": "<string>",
    "toolName": "<string>",
    "id": "<long>",
    "reportStatus": "<string>",
    "effectiveDate": "<dateTime>",
    "endDate": "<dateTime>",
    "gitTag": "<string>"
  },
  {
    "applicationId": "<string>",
    "reportName": "<string>",
    "s3Uri": "<string>",
    "toolName": "<string>",
    "id": "<long>",
    "reportStatus": "<string>",
    "effectiveDate": "<dateTime>",
    "endDate": "<dateTime>",
    "gitTag": "<string>"
  }
]