API Outcome-Centric API Policy PortalGuidance · Gates · Evidence
End-to-end guidance

How to test any API

A target repository supplies design and test evidence. The central policy repository evaluates it, generates traffic-light reports, and publishes sanitized logs.

Required target repository structure

my-api/
├── api.yaml
├── openapi.yaml
├── mocks/scenarios.yaml
└── tests/
    ├── contract/
    ├── security/
    └── failure/

Minimum workflow

  1. Add api.yaml using the compliant example as a template.
  2. Reference the API's OpenAPI specification and evidence paths.
  3. Run the API's real tests and capture the console output and JUnit report.
  4. Run the policy validator and store JSON, Markdown, and console logs in one run directory.
  5. Build or deploy the portal so users can inspect the evidence.

Example run bundle

validation-results/2026-07-27-order-api-main-abc123/
├── metadata.json
├── tests.log
├── test-results.xml
├── policy-validation.log
├── policy-report.json
└── policy-report.md

Capture logs locally

RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-order-api"
RUN_DIR="validation-results/$RUN_ID"
mkdir -p "$RUN_DIR"

set +e
pytest /path/to/my-api --junitxml "$RUN_DIR/test-results.xml" \
  2>&1 | tee "$RUN_DIR/tests.log"
TEST_EXIT=${PIPESTATUS[0]}

api-standards validate /path/to/my-api \
  --json-report "$RUN_DIR/policy-report.json" \
  --markdown-report "$RUN_DIR/policy-report.md" \
  2>&1 | tee "$RUN_DIR/policy-validation.log"
POLICY_EXIT=${PIPESTATUS[0]}
set -e
Important: The policy validator checks declared evidence and architecture gates. It does not replace unit, contract, integration, security, performance, or failure-path execution.

Traffic-light meaning

🟢 GREENRelease eligible
🟠 AMBERRemediation or risk acceptance
🔴 REDRelease blocked