Swagger/OpenAPI and REST tools

Biztraak provides a REST API alongside its GraphQL API. REST endpoints are available for common automation workflows such as projects, components, deployments, virtual machines, Git, Marketplace, team administration, and health checks.

The main web application publishes a Swagger/OpenAPI document and Swagger UI for its REST controllers. Use it alongside the route map and examples below. The repository does not currently publish an official Postman collection.

OpenAPI endpoints

• Swagger UI: /swagger
• OpenAPI document: /swagger/v1/swagger.json
• Use Authorize in Swagger UI to send a bearer access token when trying protected operations.

The document describes REST controllers in the main web application. It does not describe the standalone Compliance API or VM-agent callback authentication in full. Use the relevant service contract for those boundaries.

Route families

• Route families
  • REST routes are grouped by versioned family, such as /api/projects/v1, /api/teams/v1, /api/devops/v1, and /api/marketplace/v1.
  • Virtual-machine routes currently use /api/virtual-machines without the same v1 segment.

Using Swagger UI

1. Open /swagger on the API host.
2. Select Authorize and enter a bearer access token.
3. Expand an operation to inspect its route, parameters, request body, and response schema.
4. Use Try it out only against resources and environments you are authorized to change.

Example: list projects via REST

curl "https://<api-host>/api/projects/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response:

[
  {
    "id": "<project-id>",
    "name": "Example project"
  }
]

Why REST?

• Quick Automation: simple scripts without needing a GraphQL client
• Traceable: REST calls are logged just like GraphQL
• Interoperability: integrate with tools that prefer REST (CI/CD, monitoring, etc.)

Next steps

• API Overview → big picture of GraphQL + REST
• REST API reference → route families and request examples
• API operations → retries, asynchronous work, and compatibility guidance
• API Getting Started → authenticate and make your first request
• Authentication → how to get tokens

Swagger/OpenAPI is the generated REST contract for the main web application. The deployment’s authorization, feature flags, and workflow state still determine whether a particular operation succeeds.