API Documentation

RESTful JSON API · Base URL: http://localhost:8080/api/v1

Overview

The OpenFactstore API is a RESTful HTTP API that accepts and returns JSON. All endpoints follow standard HTTP semantics — GET for retrieval, POST to create, PUT/PATCH to update, and DELETE to remove.

When the server is running, an interactive Swagger UI is available at http://localhost:8080/swagger-ui.html with full schema documentation and a built-in request executor.

ℹ️
The OpenAPI specification (JSON) is available at http://localhost:8080/v3/api-docs and can be imported into Postman, Insomnia, or any OpenAPI-compatible tool.

Authentication

The current version does not require authentication. All API endpoints are publicly accessible. API key support is planned for a future release.

⚠️
Do not expose the API directly to the internet without a reverse proxy providing authentication. See Known Issues for production hardening guidance.

API Resources

Resource Base Path Description
Flows /api/v1/flows Compliance flow definitions (templates of required checks)
Trails /api/v1/trails Per-release deployment evidence trails
Attestations /api/v1/trails/{id}/attestations Individual compliance evidence records attached to a trail
Security Scans /api/v1/trails/{id}/security-scans Security scan results (OWASP ZAP, Snyk, Trivy)
Approvals /api/v1/approvals Release approval workflows and sign-offs
Deployment Policies /api/v1/deployment-policies Policy definitions controlling deployment gate behaviour
Deployment Gate /api/v1/gate/evaluate Evaluate whether an artifact is cleared for a target environment
Environments /api/v1/environments Tracked deployment environments (dev, staging, production)
Organisations /api/v1/organisations Multi-tenant organisation management
OPA Policies /api/v1/opa OPA bundle management and policy evaluation
Regulatory Frameworks /api/v1/frameworks SOX, PCI-DSS, GDPR framework definitions and control mappings
Compliance /api/v1/compliance Framework compliance assessment and gap analysis
Metrics /api/v1/metrics Compliance metrics and aggregated statistics

Common Patterns

Dry-run Header

All write operations (POST, PUT, DELETE) support a dry-run mode. Add the X-Dry-Run: true header to validate and simulate without persisting: 

X-Dry-Run: true

Error Responses

All errors follow a consistent JSON structure:

{
  "status": 404,
  "error": "Not Found",
  "message": "Trail with id 'abc-123' not found",
  "path": "/api/v1/trails/abc-123"
}

Example Requests

List all Flows

curl -s http://localhost:8080/api/v1/flows | jq .

Create an Attestation

curl -s -X POST http://localhost:8080/api/v1/trails/<trail-id>/attestations \
  -H "Content-Type: application/json" \
  -d '{
    "type": "security-scan",
    "passed": true,
    "details": "Trivy: 0 critical findings",
    "attestedBy": "ci-pipeline"
  }' | jq .

Evaluate Deployment Gate

curl -s -X POST http://localhost:8080/api/v1/gate/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "trailId": "<trail-id>",
    "targetEnvironment": "production"
  }' | jq .

Record a Security Scan

curl -s -X POST http://localhost:8080/api/v1/trails/<trail-id>/security-scans \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "trivy",
    "passed": true,
    "criticalCount": 0,
    "highCount": 1,
    "reportUrl": "https://ci.example.com/scans/build-42"
  }' | jq .

Interactive API (Swagger UI)

When the backend is running, the full interactive API documentation — including all request/response schemas, field descriptions, and a built-in request executor — is available at: 

http://localhost:8080/swagger-ui.html

The raw OpenAPI 3 specification is available at /v3/api-docs and can be imported into any OpenAPI-compatible client tool.