Sending Requests and Reviewing Results

​

Prerequisites

• Completed the Workspace Setup
• An active Postman environment with an API key configured
• The SCANOSS API collection imported into Postman

​

Understanding Request 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

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.

{
  "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

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.

{
  "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)

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):

{
  "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.

{
  "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

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.

{
  "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

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.

{
  "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

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.

{
  "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

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

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

​

Body Tab

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

​

Cookies Tab

​

Headers Tab

• 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

​

Response Status Codes

​

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

• purl: {{component_purl}}
• requirement: {{version_requirement}}

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

​

Path Variables

• 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

​

Basic Test Examples

​

Test 1: Verify Status Code

pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

​

Test 2: Verify Response Time

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

​

Test 3: Verify Response Structure

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

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

// 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

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

• 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

​

Example: Generate Timestamp

pm.environment.set("timestamp", new Date().toISOString());

​

Example: Construct PURL Dynamically

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

​

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

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

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

​

Variables Not Resolving

• 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

• 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

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.

• Vulnerability API
• Cryptography API
• Component Search API