> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending Requests and Reviewing Results

> Learn how to send API requests and interpret responses using Postman for SCANOSS vulnerability, cryptography, and component APIs.

## Prerequisites

Before sending requests, ensure you have:

* Completed the [Workspace Setup](workspace-setup)
* An active Postman environment with an API key configured
* The SCANOSS API collection imported into Postman

## Understanding Request Structure

All SCANOSS API requests follow a consistent structure.

### Request Components

1. **Method**: HTTP verb (GET, POST, etc.)
2. **URL**: Base URL + endpoint path + query parameters
3. **Headers**: Authentication and content type
4. **Body**: Request payload (for POST requests)

### Example Request Structure

```
GET https://api.scanoss.com/v2/vulnerabilities/component?purl=pkg:npm/express@4.18.2
Headers:
  X-Api-Key: your-api-key-here
```

## Vulnerability API Requests

### Get Component CPEs

Retrieve Common Platform Enumeration (CPE) identifiers for a component.

**Create the Request**:

1. In the **Vulnerability API** folder, add a new request.

2. Name it **"Get Component CPEs"**.

3. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{vulnerability_path}}/cpes/component`
   * **Query Params**:
     * `purl`: `pkg:github/scanoss/engine`
     * `requirement`: `>=5.0.0`

4. Click **Send**.

**Expected Response**:

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "requirement": ">=5.0.0",
    "version": "5.0.0",
    "cpes": ["cpe:2.3:a:scanoss:engine:1.0.0:*:*:*:*:*:*:*"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "CPEs Successfully retrieved"
  }
}
```

### Get Component Vulnerabilities

Retrieve known vulnerabilities for a component.

**Create the Request**:

1. Add a new request: **"Get Component Vulnerabilities"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{vulnerability_path}}/component`
   * **Query Params**:
     * `purl`: `pkg:npm/express@4.17.1`
     * `requirement`: `>=4.17.0`

3. Click **Send**.

**Expected Response**:

```json theme={null}
{
  "component": {
    "purl": "pkg:npm/express@4.17.1",
    "requirement": ">=4.17.0",
    "version": "4.17.1",
    "vulnerabilities": [
      {
        "id": "CVE-2022-24999",
        "cve": "CVE-2022-24999",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2022-24999",
        "summary": "qs before 6.10.3 allows attackers to cause a denial of service",
        "severity": "High",
        "published": "2022-11-26T22:15:00Z",
        "modified": "2022-12-02T19:54:00Z",
        "source": "NVD",
        "cvss": [
          {
            "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
            "cvss_score": 7.5,
            "cvss_severity": "High"
          }
        ]
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Vulnerabilities Successfully retrieved"
  }
}
```

### Get Component Vulnerabilities (Batch)

Query multiple components in a single request.

**Create the Request**:

1. Add a new request: **"Get Component Vulnerabilities (Batch)"**.
2. Configure:
   * **Method**: POST
   * **URL**: `{{base_url}}{{vulnerability_path}}/components`
   * **Headers**: Ensure `Content-Type: application/json` is set.
   * **Body** (raw JSON):

```json theme={null}
{
  "components": [
    {
      "purl": "pkg:npm/express@4.17.1",
      "requirement": ">=4.17.0"
    },
    {
      "purl": "pkg:npm/lodash@4.17.15",
      "requirement": ">=4.17.0"
    }
  ]
}
```

3. Click **Send**.

**Understanding Batch Responses**:

The response includes an array of components, each with their associated vulnerabilities:

```json theme={null}
{
  "components": [
    {
      "purl": "pkg:npm/express@4.17.1",
      "vulnerabilities": [...]
    },
    {
      "purl": "pkg:npm/lodash@4.17.15",
      "vulnerabilities": [...]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Vulnerabilities Successfully retrieved"
  }
}
```

## Cryptography API Requests

### Get Component Algorithms

Retrieve cryptographic algorithms used by a component.

**Create the Request**:

1. In the **Cryptography API** folder, add a new request: **"Get Component Algorithms"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{cryptography_path}}/algorithms/component`
   * **Query Params**:
     * `purl`: `pkg:github/scanoss/engine`
     * `requirement`: `>=5.0.0`

3. Click **Send**.

**Expected Response**:

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "requirement": ">=5.0.0",
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}
```

### Get Algorithms in Version Range

Retrieve cryptographic algorithms across a range of component versions.

**Create the Request**:

1. Add a new request: **"Get Component Algorithms in Range"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{cryptography_path}}/algorithms/range/component`
   * **Query Params**:
     * `purl`: `pkg:github/scanoss/engine`
     * `requirement`: `>=1.0.0`

3. Click **Send**.

**Expected Response**:

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions": ["1.0.0", "2.0.0", "3.0.0", "5.0.0"],
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "MD5",
        "strength": "Weak"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}
```

### Get Cryptographic Hints

Retrieve cryptographic libraries and protocols identified within a component.

**Create the Request**:

1. Add a new request: **"Get Component Hints"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{cryptography_path}}/hints/component`
   * **Query Params**:
     * `purl`: `pkg:github/scanoss/engine`
     * `requirement`: `>=5.0.0`

3. Click **Send**.

**Expected Response**:

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "hints": [
      {
        "id": "openssl-hint-001",
        "name": "OpenSSL",
        "description": "Industry standard cryptographic library",
        "category": "library",
        "url": "https://www.openssl.org/",
        "purl": "pkg:generic/openssl@3.0.0"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}
```

## Component Search Requests

### Search Components

Find components by name or attributes.

**Create the Request**:

1. In the **Component Search** folder, add a new request: **"Search Components"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{components_path}}/search`
   * **Query Params**:
     * `query`: `express`
     * `type`: `npm`
     * `limit`: `10`

3. Click **Send**.

### Get Component Details

Retrieve detailed information about a specific component.

**Create the Request**:

1. Add a new request: **"Get Component Details"**.

2. Configure:
   * **Method**: GET
   * **URL**: `{{base_url}}{{components_path}}/details`
   * **Query Params**:
     * `purl`: `pkg:npm/express@4.18.2`

3. Click **Send**.

## Reviewing Responses

### Response Tabs

Postman provides several tabs for analysing responses.

#### Body Tab

Displays the response content in various formats:

* **Pretty**: Formatted JSON with syntax highlighting
* **Raw**: Unformatted response text
* **Preview**: HTML rendering (for HTML responses)

#### Cookies Tab

Shows cookies set by the server, if any.

#### Headers Tab

Displays response headers:

* `Content-Type`: Response format
* `X-RateLimit-Limit`: Total requests permitted per hour
* `X-RateLimit-Remaining`: Requests remaining in the current window
* `X-RateLimit-Reset`: Time at which the rate limit resets

#### Test Results Tab

Shows the results of test scripts. See the [Testing section](#adding-tests-to-requests) for details.

### Response Status Codes

| Code | Meaning               | Description                |
| ---- | --------------------- | -------------------------- |
| 200  | OK                    | Request successful         |
| 400  | Bad Request           | Invalid request format     |
| 401  | Unauthorised          | Invalid or missing API key |
| 404  | Not Found             | Endpoint not found         |
| 429  | Too Many Requests     | Rate limit exceeded        |
| 500  | Internal Server Error | Server-side error          |

### Analysing Response Data

#### Using Pretty Print

1. Ensure **Pretty** is selected in the Body tab.
2. JSON is automatically formatted and syntax-highlighted.
3. Click the collapse/expand icons to navigate nested structures.

#### Searching Response Data

1. Press `Ctrl+F` (Windows/Linux) or `Cmd+F` (macOS).
2. Enter a search term.
3. Navigate results using the up/down arrows.

#### Copying Response Data

* **Copy entire response**: Click the copy icon in the top-right corner.
* **Copy a specific value**: Click the value to copy it to the clipboard.

## Using Variables in Requests

### Dynamic Query Parameters

Use Postman environment variables to make query parameters reusable:

**Query Params**:

* `purl`: `{{component_purl}}`
* `requirement`: `{{version_requirement}}`

**Set in Environment**:

* `component_purl`: `pkg:npm/express@4.18.2`
* `version_requirement`: `>=4.0.0`

### Path Variables

For dynamic URL segments:

**URL**: `{{base_url}}/v2/vulnerabilities/component/:component_id`

**Path Variables** tab:

* `component_id`: `express-4.18.2`

> **Note**: Ensure the path variable name in the URL (`:component_id`) matches the key defined in the Path Variables tab exactly, as the match is case-sensitive.

## Adding Tests to Requests

Validate responses automatically using Postman test scripts.

### Basic Test Examples

Open the **Tests** tab for the relevant request and add the following scripts as required.

#### Test 1: Verify Status Code

```javascript theme={null}
pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});
```

#### Test 2: Verify Response Time

```javascript theme={null}
pm.test("Response time is less than 2000ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(2000);
});
```

#### Test 3: Verify Response Structure

```javascript theme={null}
pm.test("Response has status field", function () {
  var jsonData = pm.response.json();
  pm.expect(jsonData).to.have.property("status");
  pm.expect(jsonData.status.status).to.eql("SUCCESS");
});
```

#### Test 4: Verify Component Data

```javascript theme={null}
pm.test("Component has vulnerabilities array", function () {
  var jsonData = pm.response.json();
  pm.expect(jsonData.component).to.have.property("vulnerabilities");
  pm.expect(jsonData.component.vulnerabilities).to.be.an("array");
});
```

#### Test 5: Extract and Save Data

```javascript theme={null}
// Save component version to an environment variable
var jsonData = pm.response.json();
if (jsonData.component && jsonData.component.version) {
  pm.environment.set("component_version", jsonData.component.version);
}
```

### Running Tests

1. Add test scripts to the **Tests** tab.
2. Click **Send**.
3. View results in the **Test Results** tab.
4. Green checkmarks indicate passing tests; red crosses indicate failures.

## Saving Requests as Examples

Save responses for documentation and future reference:

1. After receiving a response, click **Save Response**.
2. Choose **Save as example**.
3. Provide a descriptive name (e.g., `"Successful Response — Express 4.18.2"`).
4. The saved example will appear in the right-hand sidebar.
5. Use saved examples for documentation and to compare against future responses.

### Creating Multiple Examples

Save responses for different scenarios to provide comprehensive coverage:

* **Success**: A normal, successful response
* **Not Found**: Component not found error
* **Invalid PURL**: Malformed PURL error
* **No Vulnerabilities**: Component with no associated vulnerabilities

## Using Pre-request Scripts

Automate tasks that must run before a request is sent.

### Example: Generate Timestamp

```javascript theme={null}
pm.environment.set("timestamp", new Date().toISOString());
```

### Example: Construct PURL Dynamically

```javascript theme={null}
var namespace = pm.environment.get("namespace");
var component = pm.environment.get("component_name");
var version = pm.environment.get("version");

var purl = `pkg:${namespace}/${component}@${version}`;
pm.environment.set("generated_purl", purl);
```

## Collection Runner

Run multiple requests sequentially to test complete API workflows.

### Running a Collection

1. Click the **Collection Runner** button (top right) or press `Ctrl+Alt+R`.
2. Select your collection or folder.
3. Choose the target environment.
4. Click **Run SCANOSS API**.
5. Review the results, which show the outcome of each request in sequence.

### Use Cases

* **End-to-end workflow testing**: Validate the full API workflow in a single run.
* **Regression testing**: Confirm that existing endpoints continue to behave as expected.
* **Performance testing**: Measure and compare response times across endpoints.
* **Multi-endpoint data retrieval**: Retrieve data from multiple endpoints in a single automated run.

## Debugging Requests

### Postman Console

Use the Postman Console to inspect the full details of a request and its response:

1. Click the **Console** icon (bottom left) or press `Ctrl+Alt+C`.
2. The Console displays:
   * Complete request headers
   * Request body
   * Response headers
   * Response body
   * Log output from pre-request and test scripts

### Common Issues and Solutions

#### "Could not send request" Error

**Cause**: Network or proxy configuration issue.

**Solution**:

* Verify your internet connection.
* Disable any active VPN.
* Review proxy settings: **File → Settings → Proxy**.

#### Variables Not Resolving

**Cause**: No environment selected, or the variable is not defined in the active environment.

**Solution**:

* Ensure an environment is selected from the top-right dropdown.
* Confirm the variable exists in the active environment.
* Verify the variable name matches exactly — names are case-sensitive.

#### 401 Unauthorised

**Cause**: Invalid or missing API key.

**Solution**:

* Verify the API key value in the active environment.
* Confirm the `X-Api-Key` header is present and being sent with the request.
* Check that the authorisation header is configured correctly at the request or collection level.

## Best Practices

1. **Use environment variables**: Never hardcode API keys in request configurations.
2. **Add tests**: Validate all responses automatically using test scripts.
3. **Save examples**: Document successful and error response scenarios.
4. **Organise requests**: Use folders and consistent naming conventions.
5. **Add descriptions**: Document the purpose and expected behaviour of each request.
6. **Use pre-request scripts**: Automate repetitive setup tasks.
7. **Monitor performance**: Track response times using test assertions.
8. **Version control**: Export and back up collections regularly.

## Next Steps

Now that you can send requests and review results:

1. **Complete the collection**: Add all SCANOSS API endpoints.
2. **Write comprehensive tests**: Cover both success and error response scenarios.
3. **Automate multi-request workflows**: Use the Collection Runner to run sequences of requests.
4. **Generate documentation**: Use Postman's built-in documentation export.
5. **Export and share collections**: Share collections with your team for consistent API testing.

For detailed API endpoint documentation, see:

* [Vulnerability API](../vulnerability-api)
* [Cryptography API](../cryptography-api)
* [Component Search API](../component-search-api)