adachsoft / workflow-api-bundle
Symfony bundle providing a bearer-token-protected JSON API for workflow definitions and runs.
Package info
gitlab.com/a.adach/workflow-api-bundle
Type:symfony-bundle
pkg:composer/adachsoft/workflow-api-bundle
Requires
- php: ^8.3
- adachsoft/workflow: ^7.1
- adachsoft/workflow-launcher-contracts: ^0.2.0
- symfony/config: ^7.3
- symfony/dependency-injection: ^7.3
- symfony/http-foundation: ^7.3
- symfony/http-kernel: ^7.3
- symfony/routing: ^7.3
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^12.5
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A Symfony bundle that exposes a bearer-token-protected JSON HTTP API for inspecting workflow definitions and runs, launching workflows, and dispatching run decisions, cancellations, and timeout signals. Launch and resume requests are delegated to the configured workflow launcher contracts.
Features
- List workflow definitions and inspect an individual definition.
- List runs with status, workflow, parent-run, and deadline filters, plus pagination.
- Inspect, launch, cancel, and resume runs, including decision and timeout dispatch.
- Authenticate API requests with a configured bearer token.
- Return structured JSON errors and omit sensitive workflow configuration from definition responses.
Installation
composer require adachsoft/workflow-api-bundle
Register AdachSoft\\WorkflowApiBundle\\WorkflowApiBundle with the Symfony application if bundle auto-registration is not enabled. Configure the bundle and import its routes:
# config/packages/workflow_api.yaml
workflow_api:
token: '%env(WORKFLOW_API_TOKEN)%'
route_prefix: '/api/workflow'
max_page_size: 100
default_page_size: 50
# config/routes/workflow_api.yaml
workflow_api:
resource: '@WorkflowApiBundle/config/routes.php'
prefix: '%workflow_api.route_prefix%'
The token must be a non-empty string. max_page_size must be between 1 and 500; default_page_size must not exceed it. The application must provide implementations of the workflow repository, run query/repository, runner, launcher, and resume-dispatcher contracts used by the bundle.
Send the configured token on every request under the route prefix:
Authorization: Bearer <token>
Endpoints
All paths below are relative to the configured route prefix.
| Method | Path | Purpose |
|---|---|---|
GET | /workflows | List workflow definitions |
GET | /workflows/{workflowId} | Get a workflow definition |
GET | /runs | List runs with filters and pagination |
GET | /runs/{runId} | Get a run |
POST | /runs | Dispatch a workflow launch |
POST | /runs/{runId}/cancel | Cancel a run |
POST | /runs/{runId}/decision | Dispatch a decision for a suspended run |
POST | /runs/{runId}/timeout | Dispatch a timeout signal for a suspended run |
The run list accepts status (comma-separated statuses: running, paused, suspended, succeeded, failed, cancelled), workflow_id, parent_run_id, deadline_before (ISO-8601 date-time with a timezone), limit (1 through max_page_size), and offset (zero or greater).
Workflow definitions currently provide an identifier and no display metadata. Responses therefore use the identifier as name and an empty string as description until the workflow definition contract includes these fields.
Errors and security
API errors use a JSON object with an error containing a code, a client-safe message, and optional field-level details. Not-found errors use HTTP 404, run state conflicts use HTTP 409, invalid query or launch requests use HTTP 422, missing or invalid bearer credentials use HTTP 401, and unexpected errors use HTTP 500 with a generic message.
Definition responses deliberately exclude workflow run context and input, last-step input and output, and step configuration values except string branch targets whose keys start with on_. These fields may contain credentials such as Saurix API admin_token values. Run output and the explicitly selected suspension fields are exposed by design; keep secrets out of those fields as well.