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 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.
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.
The API is enabled by calling AddWorkflowApiCore() during ASP.NET Core service configuration and MapWorkflowApi() in the endpoint pipeline. These methods register HTTP endpoints that map to the same operations you would call from C# code - CreateInstance, ExecuteCommand, GetAvailableCommands, SetState, and others. The endpoints accept and return JSON, making them consumable from any HTTP client.
The HTTP API organizes its main endpoints into RPC, Data, and Search APIs. The RPC API exposes action-oriented operations - ExecuteCommand, GetAvailableCommands, CreateInstance, SetState, and others - that invoke WorkflowRuntime behavior. The Data API provides resource-specific read and write access to Workflow Engine persistence entities - runtimes, schemes, process instances, global and per-process parameters, timers, transitions, approvals, inbox entries, and statuses. Each entity exposes only its supported operations rather than universal CRUD. The Search API provides filtering, sorting, and pagination for supported entities.
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. 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.
Two API styles in one - the RPC API handles action-oriented workflow commands (
ExecuteCommand,CreateInstance,SetState), while the Data API provides resource-specific access to persistence entities and the Search API provides filtering, sorting, and pagination. The APIs share the same endpoint base, authentication, and OpenAPI documentation.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 throughIWorkflowApiPermissions. You can grant or deny access to specific operations per user or role.
Who it is for
Evaluator (CEO, CTO, PM): the HTTP API eliminates the need for a dedicated API development effort to expose workflow operations to non-.NET clients. The API is available as a separate Workflow Engine NEO package and covers common operations out of the box.
Developer: add AddWorkflowApiCore(), a database provider, AddWorkflowRuntime() or AddWorkflowTenants(), and MapWorkflowApi() to your ASP.NET Core pipeline. The API 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
WorkflowRuntimeinstance 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.
| 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 the API and provider packages, a runtime or tenants, and MapWorkflowApi(). | Built-in API exposure with a consistent security model and OpenAPI metadata. |
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 separate OptimaJet.Workflow.Api package. The license must enable the API groups you use. See the Editions page for details.
What endpoints does the HTTP API expose?
The API exposes RPC, Data, and Search 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. The Search API adds filtering, sorting, and pagination for supported entities. The full endpoint list is visible in the 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.