Search by

adachsoft / workflow-api-bundle

Arkadiusz Adach

Symfony bundle providing a bearer-token-protected JSON API for workflow definitions and runs.

Package info

gitlab.com/a.adach/workflow-api-bundle

Issues

Type:symfony-bundle

pkg:composer/adachsoft/workflow-api-bundle

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

v0.1.0 2026-11-20 20:36 UTC

This package is auto-updated.

Last update: 2026-11-20 19:36:54 UTC


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.

MethodPathPurpose
GET/workflowsList workflow definitions
GET/workflows/{workflowId}Get a workflow definition
GET/runsList runs with filters and pagination
GET/runs/{runId}Get a run
POST/runsDispatch a workflow launch
POST/runs/{runId}/cancelCancel a run
POST/runs/{runId}/decisionDispatch a decision for a suspended run
POST/runs/{runId}/timeoutDispatch 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.