Manually Testing Your API

In a very limited number of cases, some APIs may be incompatible with our standard Auto-API process; i.e. the process by which a user can upload their API quickly for automatic scanning. This section provides instructions on how to request manual testing of your API.

It should be understood that having your APIs tested manually is a last resort only reserved for situations where the standard process cannot be used. Please consider the onetime upfront effort in making your APIs compatible with the standard Auto-API process, against the ongoing effort and associated cost of continuing to manually test your APIs as they are. Before proceeding, please explore Adding Your API, Video Tutorial - Onboarding an API Asset and API Configuration. Ensure that manual API testing is the last resort.

Prerequisites

Before Manual API testing can begin, the following required information must be provided so that Black Duck can verify that all API operations are returning successful responses.

If a collection is provided and contains operations that are not intended to be tested, these must be clearly specified as excluded.

Prerequisite	Description
HTTP Method	Examples: DELETE https://example.com/api/users?param1=value1 GET https://example.com/api/orders?var;param2=value2&param3=value3
Domains	Domain(s) should provided and must be accessible by us. If it is an internal domain, it will be configured with our satellite appliance. If an Endpoint URL exists on multiple domains, each Endpoint URL on each unique domain will be considered a separate operation. Example: GET https://example.com/api/orders?param2=value2&param3=value3
Endpoint URL Path	Endpoint URL Path (including values for path parameters, if applicable). Example: DELETE https://example.com/api/users?param1=value1 GET https://example.com/api/orders?param2=value2&param3=value3
Required Parameters	If an operation must be sent with mandatory parameters and parameter values in order to receive a successful response, this test data must be provided. Examples: GET https://example.com/api/orders?param1=value1&param2=value2 DELETE https://example.com/api/users/215426?param2=value2
Request Headers	Required Request Headers and Associated Values
Successful Responses	Examples of the response that a user of the API can expect to receive through normal usage of the API. In most cases, a '200 OK' response will be assumed as a successful response, unless specific successful responses are provided. If any operations are intended to return errors, redirects, or unauthorized responses in order to test for access control bypasses or other logic flow circumvention, these must be specifically identified.
Authorization method and/or valid credentials (if required)	If any of the operations require valid credentials or other forms of authorization, such as tokens for authorization headers, these must be provided. If authorization tokens are provided, we must ensure that the tokens will not expire before testing can begin. If authentication operations are provided, but are not in scope for testing, these must be clearly identified as excluded from testing.
Scripts (if required)	If an operation requires the use of a script in order to generate dynamic values for each request, this script must be provided.
Business Logic Flow	If the business logic flow requires API operations to be submitted in a particular order, this information must be provided. (E.g., an operation may require a dynamic value that is returned after submitting another operation).

Prerequisite

Description

HTTP Method

Examples:

DELETE https://example.com/api/users?param1=value1
GET https://example.com/api/orders?var;param2=value2&param3=value3

Domains

Domain(s) should provided and must be accessible by us. If it is an internal domain, it will be configured with our satellite appliance. If an Endpoint URL exists on multiple domains, each Endpoint URL on each unique domain will be considered a separate operation. Example:

GET https://example.com/api/orders?param2=value2&param3=value3

Endpoint URL Path

Endpoint URL Path (including values for path parameters, if applicable). Example:

DELETE https://example.com/api/users?param1=value1
GET https://example.com/api/orders?param2=value2&param3=value3

Required Parameters

If an operation must be sent with mandatory parameters and parameter values in order to receive a successful response, this test data must be provided. Examples:

GET https://example.com/api/orders?param1=value1&param2=value2
DELETE https://example.com/api/users/215426?param2=value2

Request Headers

Required Request Headers and Associated Values

Successful Responses

Examples of the response that a user of the API can expect to receive through normal usage of the API.

In most cases, a '200 OK' response will be assumed as a successful response, unless specific successful responses are provided.

If any operations are intended to return errors, redirects, or unauthorized responses in order to test for access control bypasses or other logic flow circumvention, these must be specifically identified.

Authorization method and/or valid credentials (if required)

If any of the operations require valid credentials or other forms of authorization, such as tokens for authorization headers, these must be provided. If authorization tokens are provided, we must ensure that the tokens will not expire before testing can begin.

If authentication operations are provided, but are not in scope for testing, these must be clearly identified as excluded from testing.

Scripts (if required)

If an operation requires the use of a script in order to generate dynamic values for each request, this script must be provided.

Business Logic Flow

If the business logic flow requires API operations to be submitted in a particular order, this information must be provided. (E.g., an operation may require a dynamic value that is returned after submitting another operation).

Acceptable Documentation Types

Documentation Type	Description
Collections	Postman-compatible or SoapUI-compatible collections are preferred, and will be the fastest way to get the API scoped and onboarded for testing. Examples of Postman-compatible documentation in JSON or YAML format: Open API 3.0 specifications Swagger 2.0 specifications Postman Collection v2.1 Examples of SoapUI-compatible documentation: WSDL format (file or URL) REST API in XML format SoapUI projects
cURL Requests	Working cURL requests containing all mandatory parameters, headers, and authentication mechanisms needed in order to return a successful response for each operation.
Raw HTTP Requests	Working raw HTTP requests containing all mandatory parameters, headers, and authentication mechanisms needed in order to return a successful response for each operation.
Other Documentation types	If collections or requests cannot be provided, any other form of documentation provided must contain all of the Required Information necessary to build working requests and receive successful responses for each operation.

Documentation Type

Description

Collections

Postman-compatible or SoapUI-compatible collections are preferred, and will be the fastest way to get the API scoped and onboarded for testing.

Examples of Postman-compatible documentation in JSON or YAML format:

Open API 3.0 specifications
Swagger 2.0 specifications
Postman Collection v2.1

Examples of SoapUI-compatible documentation:

WSDL format (file or URL)
REST API in XML format
SoapUI projects

cURL Requests

Working cURL requests containing all mandatory parameters, headers, and authentication mechanisms needed in order to return a successful response for each operation.

Raw HTTP Requests

Working raw HTTP requests containing all mandatory parameters, headers, and authentication mechanisms needed in order to return a successful response for each operation.