Accessing the REST APIs

Media types

The API uses custom media types, which enable you to choose the format of the data that you receive. Requesting a media type enables a stable, backwards-compatible return.

To request a media type, you add it as an Accept header when you make a request, and as a Content-Type header when providing a request body. Responses contain a Content-Type header that describes the format.

Media types are documented with individual endpoints, but are grouped by general categories of resources. Black Duck supports the following media types:

application/vnd.blackducksoftware.admin-4+json

application/vnd.blackducksoftware.bdio+zip

application/vnd.blackducksoftware.bill-of-materials-4+json

application/vnd.blackducksoftware.bill-of-materials-5+json

application/vnd.blackducksoftware.bill-of-materials-6+json

application/vnd.blackducksoftware.component-detail-4+json

application/vnd.blackducksoftware.component-detail-5+json

application/vnd.blackducksoftware.journal-4+json

application/vnd.blackducksoftware.notification-4+json

application/vnd.blackducksoftware.policy-4+json

application/vnd.blackducksoftware.policy-5+json

application/vnd.blackducksoftware.project-detail-4+json

application/vnd.blackducksoftware.project-detail-5+json

application/vnd.blackducksoftware.report-4+json

application/vnd.blackducksoftware.scan-4+json

application/vnd.blackducksoftware.status-4+json

application/vnd.blackducksoftware.system-announcement-1+json

application/vnd.blackducksoftware.user-4+json

application/vnd.blackducksoftware.vulnerability-4+json

multipart/form-data

text/plain

Here's an example that uses a Content-Type header and an Accept header:

PUT /api/usergroups/{userGroupId}

Content-Type: application/vnd.blackducksoftware.user-4+json

Accept: application/vnd.blackducksoftware.user-4+json

Black Duck supports the following internal media types for exclusive use by the user interface:

application/vnd.blackducksoftware.internal-1+json

application/vnd.blackducksoftware.summary-1+json

Authentication

Black Duck enables you to generate one or more tokens for accessing Black Duck APIs. With access tokens, if a security breach occurs, the user’s credentials (which might be their SSO or LDAP credentials) are not directly compromised.

To access Black Duck API, you must authenticate by doing the following steps::

1. Generate an API token in Black Duck by going to the Black Duck UI, and from the user menu located on the top navigation bar, select My Access Tokens to open the My Access Tokens page where you generate your API token.

2. Pass the API token in an HTTP POST to /api/tokens/authenticate to generate a Bearer token, which you use for authorization.

3. Pass the bearer token in the authorization header of you API requests to get data from your Black Duck instance.

Generating an API token

Log in to your Black Duck instance and generate an API token.

To generate an API token:

1. From the user menu located on the top navigation bar, select My Access Tokens. The My Access Tokens page appears.

2. Click Create New Token. The Create New Token dialog box appears.
   
   

3. Type a name in the Name field.

4. Optional: In the Description field, type a description or definition.

5. Select Read Access and/or Write Access.

6. Click Create. The API token displays in a pop-up window. For security reasons, this is the only time your user API token displays. Please save this token. If the token is lost, you must regenerate it.

7. Optional: To modify an access token that you created, click the arrow in the same row as the access token name to open a drop-down menu and select Edit, Delete, or Regenerate.

Using API token

To use an API token, make an HTTP POST to /api/tokens/authenticate with the following header: Authorization: token <API token>

This produces a response with a bearer token.

The following example shows a cURL POST request in Postman with the API token (Authorization token) from Black Duck to generate the Bearer token.

curl -X POST \ 
https://<Black Duck server URL>/api/tokens/authenticate \
-H "Accept: application/vnd.blackducksoftware.user-4+json" \
-H "Authorization: token YjU4ODkyNmItODI1Ny00NjRkLWJlNDEtMWE0MzE3MmFiODgwOmMxMzNkMzkNTdjOQ=="

Using the bearer token in API calls

The following example in the Postman client shows a GET request using the bearer token that was generated from the API token.

API requests using authorization-based authentication

Note how the token provided is sent back in the subsequent request within the ‘Authorization’ header with ‘Bearer’ authentication scheme

Additionally, no CSRF, (as described here) is included since it is not required when using the ‘Authorization’ header to pass the token.

curl -v -H "Authorization: Bearer <token>" -X GET "https://<hostname>/api/components/b2d3d36c-15d3-4e1a-bef5-8e907f107048/versions/35f6d76e-e4dd-4b87-bae5-133da093dcd2"

The following example shows a cURL request for projects:

curl -X GET \
https://<Black Duck server URL>/api/projects/ \
-H "Accept: application/vnd.blackducksoftware.project-detail-4+json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJodWJfaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMS0wMDAwMDAwMDAwMDEiLCJ1c2VyX25hbWUiOiJzeXNhZG1..."

The following image shows a partial output from the cURL request.

The following example from Postman shows a request for versions of project 793f1c40-3def-4457-8aa6-2731ad4e8230:

Black Duck APIs are backward compatible within a Black Duck media type (excluding application/json).

To avoid issues, when sending or receiving data, specify the Black Duck media type in the Accept header.

Changing the expiration time for a bearer token

To extend the expiration time of a bearer token used in REST API, use the docker-compose.local-overrides.yml file to override the default setting by configuring the HUB_AUTHENTICATION_ACCESS_TOKEN_EXPIRE environment variable with the new expiration value in seconds.

The HUB_AUTHENTICATION_ACCESS_TOKEN_EXPIRE property is the number of seconds that the access tokens take to expire.

Creating a Postman Collection

Create a Postman Collection in Black Duck for import into the Postman application.

1. Log into Black Duck.

2. Open a browser tab and paste the following URL using you Black Duck server address.

   https://<your_black_duck_server>/api-doc/postman-collection-public.json

3. On the page that's generated, right-click and save as postman-collection-public.json

4. Import the saved postman-collection-public.json into your Postman application.

Generating OpenAPI endpoints

For users using OpenAPI Specification (OAS), you can generate customer-facing endpoints through /api-doc/openapi3-public.json.

1. Log into Black Duck.

2. Open a browser tab and paste the following URL using you Black Duck server address.

   https://<your_black_duck_server>/api-doc/openapi3-public.json

3. On the page that's generated, right-click and save as openapi3-public.json

4. Import the saved openapi3-public.json into your application.