Documentation Nexus IQ Server 1.16

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

22.11. Report-related REST APIs (v2)

When an evaluation occurs, an Application Composition Report is created. There are two available REST APIs associated with obtaining information related to these reports:

Reports URL REST API (v2). The Reports API provides a summary of an application’s most recent reports across the various CLM stages (e.g. build, stage release, and release). The API consists of using the GET REST resource that is part of both the applications and reports APIs.

To assist in learning to use this API we will provide both the API as well as an example using the HTTP client cURL. We’ve approached this in a step-by-step manner that will start with gathering the internal Application ID and then retrieving the report information.

[Note]

In our example below, we have isolated retrieving a report for a single application. However, if desired the reports for all applications can also be retrieved. In this case, skip to Step 2, where a corresponding tip has been included to assist.

Step 1 - Get the Application ID. First, you will use the Application’s Public ID to retrieve the internal Application ID. This is done using the following GET REST resource from our application API…

GET /api/v2/applications?publicId={YourPublicId}
[Tip]

All applications can always be returned by omitting the reference to the public id.

Using the cURL command, it would look like this:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/applications?publicId=MyApplicationID'

If you like, you can also return multiple applications by appending additional &publicId={SomeOtherPublicId} to the command above.

information will be returned (unique to your application). This has been formatted for readability:

{
    "applications": [
        {
            "id": "4537e6fe68c24dd5ac83efd97d4fc2f4",
            "publicId": "MyApplicationID",
            "name": "MyApplication",
            "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
            "contactUserName": "NewAppContact",
            "applicationTags": [
                {
                    "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
                    "tagId": "cfea8fa79df64283bd64e5b6b624ba48",
                    "applicationId": "4bb67dcfc86344e3a483832f8c496419"
                }
            ]
        }
    ]
}

From the information returned above, make note of the id. This is the internal Application ID.

[Note]

The public Id can be found via the Sonatype CLM GUI by navigating to the respective application and copying the Application ID located just below the Application Name.

Step 2 - Get Report URLs. Next we will take the internal Application ID from Step 1 and use that with the GET REST resource for the Reports API. This is done with our GET REST resource associated with our Reports API…

GET /api/v2/reports/applications/{id}
[Tip]

If you would like to obtain the report information for all applications, simply leave off the "id" and all report information for all applications will be provided.

Using cURL, it will look like this…

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/reports/applications/4bb67dcfc86344e3a483832f8c496419'

If any report information is found for the application, you will receive JSON formatted data. An example is included below.

[
    {
        "stage": "build",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2015-01-16T13:14:32.139-05:00",
        "reportHtmlUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/474ca07881554f8fbec168ec25d9616a"
    },
    {
        "stage": "stage-release",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2014-07-14T15:08:09.501-04:00",
        "reportHtmlUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/2dbfd514e5ad497598086c3e4c89c413"
    },
    {
        "stage": "release",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2014-08-31T12:01:46.179-04:00",
        "reportHtmlUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/97cccbeeb58d4aac83264993ef6bf4d8"
    }
]

Component Details by Report REST API (v2). When Sonatype CLM evaluates an application, information found during the evaluation is provided via the Application Composition Report. While this is the easiest way to review this information, it can also be exported to a JSON file using the Component Information API.

The API works by sending a REST request to the Sonatype CLM Server. This request involves using a specially formatted URL and any HTTP client. In the example we have provided we make use of cURL and the command line. In addition, we format the JSON to make it a bit more readable.

Step 1 - Sending the Request. First, let’s take a look at the GET API we’ll be using:

GET http://localhost:8070/api/v2/applications/[applicationId]/reports/[reportId]

As you may have noticed, this API uses a URL specific to the location of the report. There are two pieces of information you will need in order to retrieve the results.

  • applicationId - The Application ID for the specific application.
  • reportId - The ID of the specific report.

There are a variety of ways to retrieve this information, including gathering it by using the Component Search API. However, in our example, we’re just going to pull this information from the log output of a an evaluation using Sonatype CLM for CLI.

Here’s an excerpt of the log output produced using Sonatype CLM for CLI.

...

*********************************************************************************************
[INFO] Policy Action: None [INFO] CLM stage: build [INFO] Summary of policy
violations: 6 critical, 11 severe, 1 moderate [INFO] The detailed report can be
viewed online at
http://localhost:8070/ui/links/application/MyApp-1234/report/68b6bdb1573a40eeb4205d890b602525
[INFO]
*********************************************************************************************

NOTE:

We’ll use the link for the report to gather the information we need:

http://localhost:8070/ui/links/application/MyApp-1234/report/68b6bdb1573a40eeb4205d890b602525

In the example above, the section of the URL following "application" and before the section "report", is the Application ID. Similarly, the section after "report" is the report ID.

[Note]

The report is also presented in a full GUI. To access this, simply paste the link in your browser. However, you will need to be at least a member of the developer group for the application that has been evaluated, or you will not be able to access the report.

Now, we can download the data using our HTTP request tool.

Step 2 - Downloading Component Information. Again, in our example we are going to use cURL, though any HTTP client could be used. Here is what our request looks like:

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/applications/MyApp-1234/reports/68b6bdb1573a40eeb4205d890b602525"
[Note]

Included in our cURL example is the default username and password for the admin account. Your account credentials may vary, but are necessary in order for the request to be processed. If the username and password provided are not at least within the developer role for the application, an error will be returned.

Looking at the result through a JSON Viewer, you should see something like this:

{
   "components":[
      {
         "hash":"1249e25aebb15358bedd",
         "componentIdentifier":{
            "format":"maven",
            "coordinates":{
               "artifactId":"tomcat-util",
               "groupId":"tomcat",
               "version":"5.5.23"
            }
         },
         "proprietary":false,
         "matchState":"exact",
         "pathnames":[
            "sample-application.zip/tomcat-util-5.5.23.jar"
         ],
         "licenseData":{
            "declaredLicenses":[
               {
                  "licenseId":"Apache-2.0",
                  "licenseName":"Apache-2.0"
               }
            ],
            "observedLicenses":[
               {
                  "licenseId":"No-Sources",
                  "licenseName":"No Sources"
               }
            ],
            "overriddenLicenses":[

            ],
            "status":"Open"
         },
         "securityData":{
            "securityIssues":[
               {
                  "source":"cve",
                  "reference":"CVE-2007-3385",
                  "severity":4.3,
                  "status":"Open",
                  "url":"http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-3385",
                  "threatCategory":"severe"
               }
            ]
         }
      }
   ]
}

Now that you have access to this data, it can be packaged in a variety of ways. For example, you may want to use this as a bill of materials to include associated license data.

[Note]

In cases where you want a version of the report without any of the associated Sonatype CLM Server navigation elements (e.g. for use in a custom tool), use the embeddableReportHtmlUrl.

Additionally, CLM will return the standard HTTP response codes.