REST APIs

This section covers the REST APIs available for Sonatype IQ Server. Sonatype APIs are designed for system-to-system functionality with examples using the HTTP client curl. Following along, you may initiate the requests via a command line tool or modify the examples for other API tools. Most examples use the localhost environment with the default server credentials. You need to adjust the referencing service and credentials for your environment.

Component Identifiers

Many API reference component identifiers for searching and describing reporting components found in applications.

See Sonatype Component Identifiers for a comprehensive list of format coordinate examples.

REST API Versioning

Most Sonatype REST APIs are delineated between the API version and the Experimental APIs branch. Some APIs are solution-specific and are only available depending on your licensed solution.

For self-hosted environments, we recommend keeping your software up to date to ensure compatibility with this documentation.

Security Threats with REST APIs

Take appropriate measures to prevent security issues such as Injection and Cross-Site Scripting (XSS) when using the responses of the APIs.

IQ Server Product Version Format

IQ Server is versioned using a release identifier that is incremented sequentially for each generally available release. When referring to new functionality added to the IQ Server, typically the release number is provided. The release version is embedded as the second component of the IQ Server full product version:

Examples: Version 168, Release 169, IQ Server 170, etc

{major version}.{RELEASE VERSION}.{patch version}-{build number}

Find the IQ Server Version Using the HTTP Response Server Header

HTTP responses from IQ Server include a "Server" header that contains the full product version.

The Server header value has this format:

{product http name}/{major version}.{release version}.{minor version}-{build number}

Using an HTTP client to make the following request from the command line:

curl -sSkI http://localhost:8070/ping

HTTP/1.1 200 OK
Date: Thu, 04 Jan 2024 15:11:09 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains
Server: NexusIQ/1.183.0-01
X-Content-Type-Options: nosniff
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: text/plain
Content-Length: 5

The following example returns just the Server from the response:

curl -I http://localhost:8070/ping 2>&1 | grep -i '^Server:' | awk '{print $2}'

NexusIQ/1.183.0-01

In this example, the release version is 183.

Sonatype APIs for Cloud Environments

The following are considerations when making API calls to a Sonatype Cloud tenant.

Tenant Paths

Include the /platform path when making API calls to a Sonatype Cloud tenant.

curl -u {user}:{token} https://{tenant}.sonatype.app/platform/api/v2/applications

Rate Limits

The REST API usage in Sonatype Cloud is subject to rate limiting.

API requests rate limits: 1,500 requests / IP address / 5-minute period

When rate limits are exceeded, the service returns a 429 error code with the following message.

Rate limit exceeded. Please wait 5 minutes. If this is a recurring issue, reach out to your administrator or contact your Sonatype support representative.

Accessing REST APIs via Reverse Proxy Authentication

API requests that change data are subject to cross-site request forgery (CSRF) protection. When authentication is handled by a reverse proxy server, these requests need to include matching headers and cookie tokens. The specific value of the token is irrelevant, only that it needs to be the same for both.

required header: X-CSRF-TOKEN
required cookie: CLM-CSRF-TOKEN

curl --header "X-CSRF-TOKEN: api" --cookie "CLM-CSRF-TOKEN=api" ...