Skip to main content

Postman Guide: API Interaction and Automated Testing

1. Introduction: Our API Interaction and Testing Hub​

Postman is an essential tool for interacting with, testing, and documenting our APIs. It serves as our primary interface for manually exploring our RESTful Observability API and GraphQL Knowledge Graph endpoint, as well as for automating collections of API requests.

This guide details how we use Postman, focusing on its capabilities with runners for automated testing and its role in ensuring the reliability of our API-driven components.

Core Mission: To enable efficient API exploration, robust automated testing, and clear documentation for our critical APIs.

2. Usage in Handbook Sections​

Postman plays a key role in various operational and development workflows:

  • SRE and Monitoring/Availability: Teams use Postman collections to run manual checks or to test API endpoints during incident response when automated dashboards might be affected.
  • Architecture Monitoring: Postman can be used to manually test the health and functionality of the Observability API and the Knowledge Graph GraphQL endpoint.
  • Platform Operations: Used to interact with platform APIs for tasks that require manual intervention or specific data retrieval.
  • Quality Engineering: Postman runners are crucial for automated API testing suites, integrated into our CI/CD pipelines via GitHub Actions.
  • Ecosystem Integrations: Postman can be used to test our integrations with external APIs (e.g., Microsoft Graph API, ServiceNow API).

3. Postman Collections and Environments​

  • Collections: All documented API interactions are stored in Postman Collections. These are version-controlled and shared within our engineering team.
  • Environments: We use Postman Environments to manage variables for different deployment stages (e.g., dev, staging, prod). This allows us to easily switch endpoints and authentication tokens.
    • Common Variables:
      • baseUrl: The base URL for the API (e.g., https://api.xops.io).
      • authToken: The API key or token for authentication.
      • tenantId: For tenant-specific testing.

4. Postman Runners for Automated Testing​

The Postman Runner is a powerful feature that allows us to execute collections of requests programmatically. This is critical for automated API testing.

Use Cases:​

  • Smoke Tests: Running a basic collection of requests against an API endpoint after a deployment to ensure it's fundamentally working.
  • Integration Tests: Testing sequences of API calls that mimic a user workflow.
  • Contract Testing: Verifying that the API's response structure and data types adhere to our defined schemas.
  • Performance Benchmarking: Running a collection multiple times to get an average response time for critical endpoints.

Workflow Example: Testing the Observability API​

  1. Collection Creation: An SRE team creates a Postman Collection named "Observability API Smoke Tests." This collection includes requests for:

    • POST /v1/telemetry (to send sample metrics)
    • GET /v1/health (to check service health)
    • GET /v1/logs?service=my-service (to query recent logs)

  2. Environment Setup: A staging environment is configured with baseUrl pointing to the staging Observability API and a valid authToken.

  3. Running the Collection: The Postman Runner is used to execute this collection against the staging environment.

    • The number of iterations is set to 1.
    • The staging environment is selected.
    • The collection is run.

  4. Assertions: Postman allows us to add JavaScript-based assertions to each request. For example, for the /v1/health endpoint, we assert that the response status code is 200 and that the response body contains "status": "healthy".

  5. Integration with CI/CD:

    • While Postman itself is GUI-based, its Newman CLI runner allows us to integrate Postman collections into our CI/CD pipelines (e.g., GitHub Actions).
    • A GitHub Action can be configured to run a Postman collection using Newman, reporting success or failure back to the pipeline. This is crucial for ensuring API contracts are maintained.

5. Example: Testing the Knowledge Graph GraphQL Endpoint​

The Knowledge Graph exposes its data via a GraphQL endpoint. Postman can be used to craft and execute GraphQL queries.

  1. Request Type: Set the request type to GraphQL.
  2. GraphQL Query: In the "Body" tab, select "GraphQL" and enter the query. 
    query GetCustomerData($customerId: ID!) {
      customer(id: $customerId) {
        name
        operationalStatus
        recentIncidents(limit: 5) {
          id
          severity
          timestamp
        }
      }
    }
  3. Variables: In the "Query Variables" section, define the variables for the query (e.g., {"customerId": "cust_abc123"}).
  4. Authentication: Use the configured environment's authToken in the Headers tab.
  5. Assertions: Add assertions to check the response structure and values, e.g., pm.response.json().data.customer.name should not be empty.

6. Best Practices​

  • Keep Collections Updated: As APIs evolve, ensure your Postman collections are updated. Sync them with version control.
  • Use Environments: Always use Postman Environments to manage different deployment targets and credentials.
  • Write Assertions: Never just send a request; always write assertions to validate the response.
  • Parameterize Requests: Use variables extensively to make your requests reusable.
  • Newman for Automation: Integrate your collections into CI/CD pipelines using Newman for automated testing.
  • Organize Collections: Group related requests into folders within your collections.

By leveraging Postman effectively, we ensure our APIs are not only well-documented but also rigorously tested and reliable.