HTTP API
Workflow Engine Web API is the OptimaJet.Workflow.Api ASP.NET Core package and integration layer. Calling MapWorkflowApi() publishes the Workflow Engine HTTP API endpoint surface. That surface includes Designer API and health endpoints, plus the license-controlled Data API and RPC API groups. Data API covers both direct resource routes under /data and search, filtering, sorting, and pagination routes under /search.
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.
Workflow Engine Web API is the 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 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
/dataand 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, andSetStatethat invokeWorkflowRuntimebehavior. - 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. A NEO license can enable the Data API and RPC API groups.
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, including filtering, sorting, and pagination through its/searchoperations. 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. Workflow Engine Web API is distributed as a separate package, and licensed NEO capabilities add Data API and RPC API 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 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. |
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 Data API, RPC 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 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.