Skip to main content

Component Search REST API

The Component Search API returns the metadata for a component. This API searches application reports for the components specified.

Using GET requests it allows you to retrieve component information such as application ID, application name, report HTML URL, component hash, component coordinates, the highest threat level of the policy violations (for the found component), and dependency information.

Below, we’ve provided an example of the GET request. We’ve done this using the HTTP client cURL. Of course, you could use any HTTP client tool. Additionally, to help demonstrate the use of the API, we’ve broken out the various pieces for this request and provided an example of data that is retrieved.

Searching for Components

First, make sure your IQ Server is started. Also, as we mentioned, you will need to have evaluated at least one application. With those two things completed, let’s take a look at the GET API.

GET /api/v2/search/component

Now, in addition to this, you will need to add two parameters - the stage, and then add your search parameters.

Stage

Typically the stage represents the development lifecycle of your product. There are four stages that are currently supported.

These include:

  • build

  • stage-release

  • release

  • operate

Entering any of these for the stage ID will pull from that specific stage’s evaluation data.

Next up, you need to set the component search parameters using any combination of these options:

Search Parameters

The search parameters can either represent a direct hash of a component, a componentIdentifier object or a packageUrl string.

  • hash - the component hash (e.g. hash=1234567890).

  • componentIdentifier - this is an object that contains the coordinates of the component and its format.

  • format - this is the format of the component (e.g. "maven" or "a-name" or "python").

  • coordinates - this object contains the name/value pairs for identifying coordinates (e.g. artifactId, groupId, version, extension, and classifier).

  • packageUrl - this is an alternative representation (PURL-spec) of the component identifier.

Note

The request must URL encode the component identifier and the package-Url payload.

Maven example

Now, let’s look at an example. Consider a case where we wanted to find all components within the group ID "tomcat", for any applications evaluated during the Build stage. Using the information above, as well as cURL and an encoded URL, here is what we would have…

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/search/component?stageId=build&componentIdentifier=%7B%22format%22%3A%22maven%22%2C%22coordinates%22%3A%7B%22groupId%22%3A%22tomcat%22%2C%22artifactId%22%3A%22*%22%2C%22version%22%3A%22*%22%2C%22extension%22%3A%22*%22%2C%22classifier%22%3A%22*%22%7D%7D"

The above is an encoded URL, the non-encoded URL is as follows.

"http://localhost:8070/api/v2/search/component?stageId=build&componentIdentifier={"format":"maven","coordinates":{"groupId":"tomcat","artifactId":"*","version":"*","extension":"*","classifier":"*"}}"

Package-URL example

Let's look at the same example with the packageUrl parameter instead of the componentIdentifier payload.

The package-URL format for the above coordinates is.

pkg:maven/tomcat/*@*?type=*&classifier=*

And the cURL command with its URL encoded equivalent form would be.

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/search/component?stageId=build&packageUrl=pkg%3Amaven%2Ftomcat%2F*%40*%3Ftype%3D*%26classifier%3D*

JavaScript example

We call the coordinate system for JavaScript "a-name", which is short for the authoritative name. If we want to search for any applications that contain the JavaScript package vizion, version 0.1.0 we would use the following componentIdentifier object

"http://localhost:8070/api/v2/search/component?stageId=build&componentIdentifier={"format":"a-name","coordinates":{"name":"vizion","qualifier":"","version":"0.1.0"}}"

Python example

If we want to search for a python PyPi package pyOpenSSL in version 17.0.0 we would use the below componentIdentifier

"http://localhost:8070/api/v2/search/component?stageId=build&componentIdentifier={"format":"pypi","coordinates":{"name":"pyOpenSSL","qualifier":"py2.py3-none-any","version":"17.0.0","extension":"whl"}}"

Note

The results are filtered based on the permissions of the credentials you use.

Only the package Url is processed when both are included during a search. The package URL is given a higher precedence when compared with the component identifier.

Output

The response from the API is a JSON object. Assuming we ran the maven query searching for tomcat components, the JSON response will list all applications containing the tomcat component.

An example output:

{
  "criteria": {
    "stageId": "build",
    "hash": null,
    "packageUrl": null,
    "componentIdentifier": {
      "format": "maven",
      "coordinates": {
        "groupId": "tomcat",
        "artifactId": "*",
        "version": "*",
        "extension": "*",
        "classifier": "*"
      }
    }
  },
  "results": [
    {
      "applicationId": "MyApp-1234",
      "applicationName": "My Application 2",
      "reportHtmlUrl": "ui/links/application/MyApp-1234/report/c81991938f304f30bc139ea13cf93cd5",
      "reportUrl": "http://localhost:8070/ui/links/application/MyApp-1234/report/c81991938f304f30bc139ea13cf93cd5",
      "hash": "1249e25aebb15358bedd",
          "packageUrl" : "pkg:maven/tomcat-util/tomcat@5.5.23?type=jar",
      "componentIdentifier": {
        "format": "maven",
        "coordinates": {
          "artifactId": "tomcat-util",
          "classifier": "",
          "extension": "jar",
          "groupId": "tomcat",
          "version": "5.5.23"
        }
      },
      "dependencyData" : {
          "directDependency": false, 
          "parentComponentPurls":[
                        "pkg:maven/tomcat-util/tomcat@5.5.23?type=jar",
                        "pkg:maven/org.example/ACME-service@1.2.0-SNAPSHOT?type=jar",
                  ],
          "innerSource" : false, 
                  "innerSourceData":[
                    {
                          "ownerApplicationName": "My Application 2",
                          "ownerApplicationId": "MyApp-1234",
                          "innerSourceComponentPurl": "pkg:maven/org.example/ACME-data@1.0-SNAPSHOT?type=jar"
                    }
                  ]
      }
    }
  ]
}

Note

The returned component hash is a truncated SHA1 and is meant to be used as an identifier to pass into subsequent REST API calls. It is not a checksum.

Using Wildcards

The Component Search API supports the use of wildcards when searching using the GAVEC (coordinates). This endpoint follows the same logic as the coordinates policy condition.