# HTTP API

Integrating a .NET workflow engine with a non-.NET frontend or service usually means building a custom API layer. Every new endpoint -
create instance, execute command, check state - has to be written, tested, and maintained. The API surface grows with every workflow
operation the frontend needs.

The Workflow Engine HTTP API exposes [WorkflowRuntime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/) operations as HTTP endpoints. Any client that
speaks HTTP - whether .NET, JavaScript, Python, Java, or another .NET service - can create process instances, execute commands, query
available commands, and read process state without writing a custom API layer.

With the HTTP API, your React frontend calls `ExecuteCommand` via `fetch()` directly. Your Python microservice starts a process instance by
POSTing to the create-instance endpoint. Your low-code platform connects over REST without custom middleware.
With the [Forms API extension](https://docs.workflowengine.io/evaluate/workflow-engine-features/workflow-forms/), a form frontend can load, save,
and execute process-bound forms without a custom forms controller.

## What it is

Think of the HTTP API as a remote control for the workflow engine. Instead of calling C# methods directly, you send HTTP requests to
predefined endpoints. The API translates each request into the corresponding runtime operation and returns the result as JSON.

Workflow Engine Web API is the [OptimaJet.Workflow.Api](https://www.nuget.org/packages/OptimaJet.Workflow.Api) ASP\.NET Core package and
integration layer that hosts this interface. A host calls `AddWorkflowApiCore()` to register its services and `MapWorkflowApi()` to publish
Workflow Engine HTTP API endpoints in the application routing pipeline. Those endpoints use the registered Workflow Runtime, persistence
provider, tenants, and security configuration.

![Workflow Engine Web API uses MapWorkflowApi to publish Data, RPC, Forms, Designer, and health endpoints](https://docs.workflowengine.io/images/evaluate/web-api-http-api.svg)

*Workflow Engine Web API supplies the ASP\.NET Core integration. Workflow Engine HTTP API names the HTTP endpoints published by that
integration.*

The Workflow Engine HTTP API endpoint surface contains these groups:

- **Data API** provides resource-specific read and write operations under `/data` and collection search operations under `/search`.
  Search supports filtering, sorting, and pagination for the applicable entities. Each entity exposes only its supported operations rather
  than universal CRUD.
- **RPC API** exposes action-oriented operations such as `ExecuteCommand`, `GetAvailableCommands`, `CreateInstance`, and `SetState` that
  invoke `WorkflowRuntime` behavior.
- **Forms API** is a group supplied by the separate `OptimaJet.Workflow.Api.Forms` package. It exposes four
  POST operations under `/forms`: `get-form`, `get-executable-forms`, `save-form`, and `execute-form`. These operations
  connect HTTP clients to the Forms Plugin without a custom controller.
- **Designer API** supplies the backend endpoint used by Workflow Designer.
- **Health endpoints** report liveness and readiness for the API host, Workflow Runtime, and configured tenants.

Designer API and health endpoints are available when Workflow Engine Web API is attached to classic Workflow Engine. The Data API and
RPC API groups are capabilities of [Workflow Engine NEO](https://workflowengine.io/products/workflow-engine-neo/). Forms API requires the
`Forms` license capability and registration from the
`OptimaJet.Workflow.Api.Forms` package.

The API includes built-in OpenAPI / Swagger metadata. You can publish it with native ASP\.NET Core
OpenAPI or with `AddEndpointsApiExplorer()` and `AddSwaggerGen()`. This lets teams using non-.NET stacks explore and test the API without
reading C# documentation.

Security uses standard ASP\.NET Core authentication middleware. The host can use JWT bearer tokens, cookie authentication, or any other
scheme registered in its pipeline. When `AddWorkflowApiSecurity()` is registered, authorization uses a
granular permission system - each endpoint has a unique `OperationId`, and access is controlled through the `IWorkflowApiPermissions`
interface. This lets you grant or deny access to specific operations per user or role, down to individual endpoints.

**For developers:** add `services.AddWorkflowApiCore()`, a provider-specific registration like `services.AddWorkflowApiMssql()`, and
`services.AddWorkflowRuntime()` to your service collection, then call `app.MapWorkflowApi()` on the application builder.
To add Forms API, reference `OptimaJet.Workflow.Api.Forms` and call `services.AddFormsPlugin(...)` before
`MapWorkflowApi()`. Optional `AddFormDataPipelineStep<TStep>(order)` registrations transform incoming form data in
ascending order and outgoing form data in reverse order.
See Web API Setup for a step-by-step guide.

## Why it matters

The HTTP API delivers these outcomes:

- **No custom API layer** - common runtime operations the frontend needs are already exposed as HTTP endpoints. Creating instances,
  executing commands, reading state, and querying history are built in.

- **Several API styles in one host** - the **RPC API** handles action-oriented workflow commands such as
  `ExecuteCommand`, `CreateInstance`, and `SetState`,
  while the **Data API** provides resource-specific access to persistence entities, including filtering, sorting, and pagination through
  its `/search` operations. The **Forms API** handles form discovery, drafts, and form command execution.
  The API groups share the same endpoint base, authentication, and OpenAPI documentation.

- **Forms without a custom controller** - `AddFormsPlugin(...)` registers the Forms Plugin and its HTTP operations.
  The Forms API uses the same runtime or tenant selection as the other endpoint groups.

- **Language-agnostic integration** - any HTTP client can interact with the workflow engine. JavaScript, Python, Java, Go, Ruby, or low-code
  platforms all use the same REST endpoints and JSON payloads.

- **OpenAPI documentation** - the API endpoint metadata can be published in an OpenAPI document and Swagger UI when OpenAPI is configured.
  Teams can explore and test endpoints without reading C# documentation or inspecting the source code.

- **Consistent security model** - the API can use ASP\.NET Core authentication middleware with a granular permission
  system. Each endpoint is identified by a unique `OperationId`, and access is controlled through
  `IWorkflowApiPermissions`. You can grant or deny access to specific operations per user or role.

## Who it is for

**Developer:** add `AddWorkflowApiCore()`, a database provider, `AddWorkflowRuntime()` or `AddWorkflowTenants()`, and `MapWorkflowApi()` to
your ASP\.NET Core pipeline. Add `AddFormsPlugin(...)` when the application needs the Forms API. The endpoints are
ready without writing controller code.
See Web API Setup and Web API Security for integration details.

**Enterprise architect:** the API runs inside your ASP\.NET Core application and uses standard authentication middleware. Each endpoint has
an `OperationId` that can be used for granular access control through the `IWorkflowApiPermissions` interface. The endpoint metadata can be
used to generate an OpenAPI schema for API gateways, documentation tools, and code generators.

## When to use it

Use the HTTP API whenever you need to call workflow operations from another process, regardless of the client technology. Typical examples:

- **Single-page application frontend** - a React or Vue.js application calls workflow operations via `fetch()` or a generated API client. No
  backend-for-frontend layer is needed.

- **.NET microservices** - another .NET service in your architecture calls workflow operations over HTTP instead of hosting a
  `WorkflowRuntime` instance directly. The API provides a language-native integration point without tight coupling.

- **Polyglot microservices** - a Python, Java, or Go service needs to start a process instance or check process state. The API provides REST
  endpoints that any language can call.

- **Low-code and no-code integration** - tools like Power Automate, Zapier, or custom automation platforms connect over HTTP. The Workflow
  Engine API exposes workflow operations as standard REST endpoints they can call.

## How it compares

The main alternative to the built-in HTTP API is building a custom API layer. The table below shows the tradeoffs.

Table: Comparison of HTTP API approaches

| Approach                     | What it requires                                                                                          | Result                                                                                          |
|------------------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| **Build a custom API**       | Define controllers, serialize requests/responses, document endpoints, handle errors, maintain versioning. | Engineering effort for every new operation. Risk of inconsistent security or missing endpoints. |
| **Workflow Engine HTTP API** | Register Workflow Engine Web API, a provider, a runtime or tenants, and call `MapWorkflowApi()`.         | Built-in API exposure with a consistent security model and OpenAPI metadata.                    |

## See also

- Web API Setup: Add AddWorkflowApiCore and MapWorkflowApi to your ASP.NET Core pipeline.
- Web API Security: Configure host authentication and operation or tenant permissions.
- OpenAPI / Swagger: Publish API endpoint metadata for non-.NET clients.
- Web API Multitenancy: Select tenants through a request header or configured default.

## Frequently asked questions

**Do I need a specific license or edition to use the HTTP API?**

The RPC and Data APIs are Workflow Engine NEO capabilities distributed in the `OptimaJet.Workflow.Api` package.
Forms API is available starting with Workflow Engine 23.0.0. It is supplied by `OptimaJet.Workflow.Api.Forms` and requires the
`Forms` license capability. The license must enable every API group you register. See the
[Editions](https://docs.workflowengine.io/evaluate/workflow-engine-editions/) page for details.

**What endpoints does the HTTP API expose?**

Depending on registered packages and licensed capabilities, the API exposes Data API, RPC API, Forms API, Designer
API, and health endpoints. The **RPC API** covers action-oriented operations -
`CreateInstance`, `ExecuteCommand`, `GetAvailableCommands`, `SetState`, process history, and subprocess tree queries. The **Data API**
covers resource-specific read and write access to runtimes, schemes, process instances, parameters, timers, transitions, approvals, inbox
entries, statuses, and global parameters. Its `/search` operations add filtering, sorting, and pagination for supported
entities. The **Forms API** retrieves standalone or process-bound forms, discovers executable forms, saves
drafts, and executes form commands. The full endpoint list is visible in Swagger UI when OpenAPI is enabled.

**How does the API handle authentication and authorization?**

The host uses ASP\.NET Core authentication middleware and can support JWT bearer tokens, cookie authentication, and any other scheme
registered in its pipeline. When `AddWorkflowApiSecurity()` is registered, authorization uses a granular permission system - each endpoint
has a unique `OperationId`, and access is controlled per operation via the `IWorkflowApiPermissions` interface. This lets you grant or deny
access to specific API endpoints per user or role, independent of the workflow runtime's own actor rules.

**Does the HTTP API support multitenancy?**

Yes. Register tenants with `AddWorkflowTenants()`. A request selects a registered tenant through the `Workflow-Api-Tenant-ID` header or
`WorkflowApiCoreOptions.DefaultTenantId`; a permission claim can separately restrict the tenants the caller may access. See
the Web API Multitenancy documentation for configuration details.

**Can I use the HTTP API with Swagger / OpenAPI?**

Yes. The API supplies ASP\.NET Core endpoint metadata. Configure native `AddOpenApi()` or `AddEndpointsApiExplorer()` with `AddSwaggerGen()`
to generate an OpenAPI document; Swagger UI is an optional host component.