APIs and Integration
APIs and Integration distinguishes the contracts applications use to work with Workflow Engine and Workflow Server. Workflow Engine exposes direct .NET APIs inside the host process. Workflow Engine Web API is the ASP.NET Core integration package for an embedded Workflow Runtime. Its MapWorkflowApi() method publishes Workflow Engine HTTP API endpoints. With classic Workflow Engine, those endpoints include Designer API and Health Check API. NEO capabilities add the Data API and RPC API groups. Workflow Server runs as a standalone service and exposes its separate Workflow API over HTTP.
Workflow Engine API surfaces
The API surface depends on whether the application embeds Workflow Runtime, uses Workflow Engine Web API to publish Workflow Engine HTTP API, connects Workflow Designer, or manages the separate Workflow Server Product. The following names identify those boundaries.
In-Process API: Direct .NET calls to WorkflowRuntime inside the host application. The In-Process API does not use HTTP.
Bulk API: The In-Process API exposed as runtime.Bulk for applying supported operations to multiple Process Instances in parallel. It returns a result for each item, so one failed item does not imply one all-or-nothing transaction for the complete batch.
Offline API: The In-Process API exposed as WorkflowRuntime.OfflineApi for building Approval Maps and executing ordered batches of Commands. An Approval Map is a simplified view of the Command-triggered Transitions and unconditional Automatic Transitions that connect Scheme Activities; the Process Instance overload filters this view for an Identity and marks Activities that are active in the process tree. Command batches are executed in DateTime order within each Process ID. The ProcessDefinition Approval Map overload does not itself access persistence, while Process Instance maps and command execution read or update persisted Process Instances. Offline is the API name, not a general mode for running Workflow Engine without a persistence store.
Workflow Engine Web API: The OptimaJet.Workflow.Api ASP.NET Core package and integration layer for hosting an embedded Workflow Runtime in a web application. A host registers its services with AddWorkflowApiCore(), connects a Workflow Runtime and persistence provider, and calls MapWorkflowApi() in the endpoint pipeline. The integration provides endpoint routing, tenant selection, security hooks, and OpenAPI metadata. Web API is the accepted short form after the Product is clear.
Workflow Engine HTTP API: The canonical full name of the HTTP endpoint surface published by Workflow Engine Web API through MapWorkflowApi(). HTTP API is the accepted short form after the Product is clear. The endpoint surface includes Designer API and Health Check API when the Web API package is attached to classic Workflow Engine. A NEO license can enable the Data API and RPC API groups. Data API includes direct resource operations under /data and collection search operations under /search. REST API refers specifically to the resource-oriented Data API operations rather than the complete HTTP endpoint surface. Its OpenAPI specification describes the HTTP contract, and Swagger UI presents that specification interactively; neither name identifies another API.
Data API: The NEO resource-oriented part of Workflow Engine HTTP API for Schemes, Process Instances, Parameters, timers, approvals, and related persisted data. It includes resource operations under /data and operations for searching collections under /search, with search text, filters, sorting, and pagination supplied in the request body. Both route groups use the same data providers and are enabled by the same License restriction, named DataApi in code. The /search prefix identifies Data API operations; it does not name another API. Data API is not included when the Web API package is used with classic Workflow Engine alone. Each resource exposes only its supported operations rather than universal CRUD.
RPC API: The NEO operation-oriented part of Workflow Engine HTTP API. RPC operations invoke Workflow Runtime behavior such as creating a Process Instance, executing a Command, or setting State. RPC API is not included when the Web API package is used with classic Workflow Engine alone.
Designer API: The backend contract used by Workflow Designer to load and save Schemes and perform supporting operations such as compiling Code Actions. The Core library exposes synchronous and asynchronous entry points named DesignerAPI and DesignerAPIAsync; each call supplies request parameters and can include an uploaded file stream. Workflow Engine Web API maps this contract to an ASP.NET Core route such as /workflow-api/designer, including when the package is attached to classic Workflow Engine. Designer API does not require Data API or RPC API and is not the complete Workflow Engine HTTP API.
Health Check API: The liveness and readiness endpoints included in Workflow Engine HTTP API. The liveness endpoint reports whether the ASP.NET Core service is running, while readiness and tenant-readiness check Workflow Runtime and database availability. Health Check API remains available when the package is attached to classic Workflow Engine and does not require Data API or RPC API.
Workflow API: The HTTP API exposed by Workflow Server for managing the standalone service and executing workflows. Applications call Workflow API instead of embedding Workflow Runtime directly. Workflow API belongs to Workflow Server and is distinct from Workflow Engine HTTP API, which Workflow Engine Web API publishes for an embedded Workflow Runtime.
Callback API: The Workflow Server HTTP contract for calling workflow logic hosted on external callback servers. Workflow Server uses it to discover and call Actions, Conditions, and Rules used for authorization. The contract also includes remote Scheme generation, event notifications, and getting or setting Parameters through callback servers. Callback servers are configured in the Workflow Server admin panel. Callback API is not Workflow Engine RPC API.
See also
These pages explain the integration surfaces and their configuration.
- Workflow Engine HTTP API describes the endpoint surface and the Workflow Engine Web API integration that publishes it.
- Workflow Server Callback API documents callback-server configuration and supported methods.
- Bulk API explains supported batch operations.
- Glossary overview links to the other terminology subjects.
Frequently asked questions
How do Workflow Engine Web API and Workflow Engine HTTP API relate?
Workflow Engine Web API is the ASP.NET Core package and integration layer. Its MapWorkflowApi() method publishes the Workflow Engine HTTP API endpoints in the host application. Web API is the short form of Workflow Engine Web API; HTTP API is the short form of Workflow Engine HTTP API.
Which API should I use to start a Process Instance or execute a Command from another application?
Use RPC API for operations that invoke Workflow Runtime behavior, such as creating a Process Instance, executing a Command, or setting State. Use Data API to read, search, or update supported persisted resources.
Can classic Workflow Engine use Workflow Engine HTTP API?
Yes. The Web API package can be attached to classic Workflow Engine to map Designer API and Health Check API into an ASP.NET Core application. Data API and RPC API remain unavailable unless the License enables the corresponding NEO capabilities.
Do I need Workflow Server to expose an embedded Workflow Engine over HTTP?
No. Add Workflow Engine Web API to the ASP.NET Core host and call MapWorkflowApi() to publish Workflow Engine HTTP API. Use Workflow Server when you need a separate standalone Product instead of an embedded Workflow Runtime.
Is Workflow Server's Workflow API the same as Workflow Engine HTTP API?
No. Workflow API is the client-facing HTTP contract of the separate Workflow Server Product. Workflow Engine HTTP API is the ASP.NET Core integration for applications that embed Workflow Engine; NEO capabilities can add its Data and RPC groups.