https://github.com/optimajet/workflowengineapi.net

Workflow Engine HTTP API
https://github.com/optimajet/workflowengineapi.net

Last synced: over 1 year ago
JSON representation

Workflow Engine HTTP API

• Host: GitHub
• URL: https://github.com/optimajet/workflowengineapi.net
• Owner: optimajet
• Created: 2024-08-13T07:37:22.000Z (almost 2 years ago)
• Default Branch: master
• Last Pushed: 2025-03-10T18:45:12.000Z (over 1 year ago)
• Last Synced: 2025-03-10T19:41:52.104Z (over 1 year ago)
• Language: C#
• Size: 7.16 MB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Workflow Engine API Sample

This repository contains a sample integration of the Workflow Engine API into an ASP.NET application. The Workflow

Engine Web API is a library for the ASP.NET framework that allows you to integrate a ready-made API into your

application for managing data and processes within Workflow Engine instances. This module is easily integrable and

highly customizable, saving you from the routine development needed to integrate Workflow Engine into your web

ecosystem.

### Key Features

1. **RESTful Data API**: Safely interact with the Workflow Engine database without risking internal process disruptions.

2. **RPC API** *(Coming soon…)*: Remotely manage the Workflow Engine Runtime instance.

3. **Permission-based Security**: Fine-tune access to each API endpoint and generate claims for your users.

Learn more about Workflow Engine API on the [documentation website](https://workflowengine.io/documentation/web-api).

## Get Started

1. Install the [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).

2. Install [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4)

   version 7 or higher.

3. Install and run [Docker](https://www.docker.com/products/docker-desktop/).

4. Clone the repository.

    ```bash

    git clone git@github.com:optimajet/WorkflowEngineApi.NET.git workflow-api-sample

    ```

5. Go to the solution directory:

    ```bash

    cd workflow-api-sample

    ```

6. Add your license key to the `./WorkflowApi/appsettings.json` file:

    ```json

    {

      "WorkflowApiCoreOptions": {

        "LicenseKey": "your_license_key"

      }

    }

    ```

7. Install the OpenAPI specification generator tool:

    ```bash

    dotnet tool install --global Swashbuckle.AspNetCore.Cli --version 6.6.2

    ```

8. Build the solution:

    ```bash

    dotnet build

    ```

9. Run integration tests:

    ```bash

    pwsh ./Scripts/Tests/run-tests.ps1 -Providers "Mssql"

    ```

10. Launch the WorkflowApi project:

    ```bash

    dotnet run --project ./WorkflowApi

    ```

11. Open the Swagger UI in your browser at [localhost:7169/swagger](https://localhost:7169/swagger/index.html).

12. Send GET request to the auth controller with `name=admin&password=admin` to get an API access token with all privileges:

    - Using link: [localhost:7169/auth?name=admin&password=admin](https://localhost:7169/auth?name=admin&password=admin)

    - Using curl:

    

        ```bash

        curl -k -X GET "https://localhost:7169/auth?name=admin&password=admin" -H "Accept: text/plain"

        ```

      

    - Using Swagger UI:

        1. Scroll to the `Auth` controller.

        2. Click on the `GET /auth` endpoint.

        3. Click on the `Try it out` button.

        4. Enter `admin` in the `name` field.

        5. Enter `admin` in the `password` field.

        6. Click on the `Execute` button.

        7. Copy the token from the response body.

        8. Click on the `Authorize` button in the top right corner.

        9. Paste the token into the `Value` field.

        10. Click on the `Authorize` button.

13. Try out the API endpoints using the Swagger UI, get runtimes for an example:

    - Using curl:

        ```bash

        curl -k -X GET "https://localhost:7169/workflow-api/data/runtimes" -H "Accept: application/json" -H "Authorization: Bearer PUT_YOUR_TOKEN_HERE"

        ```

    - Using Swagger UI:

        1. Scroll to the `Runtimes` controller.

        2. Click on the `GET /workflow-api/data/runtimes` endpoint.

        3. Click on the `Try it out` button.

        4. Click on the `Execute` button.

![How to use Swagger UI](./Images/how-to-use-swagger-ui.gif)

## Solution Structure

The solution consists of three projects:

- **WorkflowApi** — A sample web application that demonstrates how to use the `OptimaJet.Workflow.Api` library.

- **WorkflowApi.Client** — A sample WorkflowApi client application generated using OpenAPI specification.

- **WorkflowApi.Client.Tests** — An integration tests project based on WorkflowApi client that checks all API endpoints

  work correctly.

### Solution Building Pipeline

When you run the build of the solution in the `Debug` configuration, an unusual build pipeline is used:

1. Build WorkflowApi.

2. After building WorkflowApi in debug configuration, the OpenAPI specification is generated by

   the `Swashbuckle.AspNetCore.Cli` tool and placed in `./WorkflowApi/.swagger`.

3. After specification generation, `./WorkflowApi/.swagger/swagger.yaml` is linted by executing

   `./Scripts/lint-swagger.ps1` script.

4. After the specification is linted, `WorkflowApi.Client` is generated by executing `./Scripts/build-client.ps1` and

   placed in the `./.generated` folder.

5. In the same script, the generated client is copied to the `./WorkflowApi.Client` project except for

   the `WorkflowApi.Client.csproj` file.

6. Build `WorkflowApi.Client`.

7. Build `WorkflowApi.Client.Tests`.

### Scripts

Scripts are stored in the `./Scripts` folder.

- `build-client.ps1` - Generates the `WorkflowApi.Client` project using the OpenAPI specification

  in `./WorkflowApi/.swagger`.

- `lint-swagger.ps1` - Lints the OpenAPI specification generated at `/WorkflowApi/.swagger/swagger.yaml` using

  the `dshanley/vacuum` Docker image.

- `Tests/run-tests.ps1` - Runs integration tests for the `WorkflowApi.Client.Tests` project. Ensure Docker is installed

  and running before executing. Has a `-Providers` parameter to specify the list of providers to test.

- `Tests/create-containers.ps1` - Creates Docker containers for integration testing in the `WorkflowApi.Client.Tests`

  project. Ensure Docker is installed and running before executing. Has a `-Providers` parameter to specify the list of

  providers to test.

- `Tests/remove-containers.ps1` - Removes containers created by the previous script. Ensure Docker is installed and

  running before executing. Has a `-Providers` parameter to specify the list of providers to remove.

- `Tests/containers.json` - Configuration for the created containers.

## Details

This section dives into the elements of this project to understand the general principles of the Workflow API and its

implementation in this sample.

### App Building and Configuration

The `AppBuilder` class is used to build the ASP.NET `WebApplication` instead of configuring it in the `Program` class.

This allows for easy integration testing, enabling another project to create multiple application hosts with predefined

settings and send requests to them.

The `Configuration` class contains part of the application settings, which can be overridden in `appsettings.json`.

During service configuration, an instance of this class is serialized from the initial configuration and then added back

to include default settings. This configuration approach allows easy use in integration testing and substitution if

necessary.

The application also adds several essential services, including controllers, authentication with authorization, Swagger

generator, and DbContext. Each service has a `ConfigureX` method that takes an `options` object for configuration.

All possible Workflow API Data libraries are included in the application, and the provider is selected based on

the `Configuration.Provider` setting.

The provider's name chooses the connection string, with the default string

used for the internal database of the Workflow API sample.

Finally, the WorkflowAPI is connected. In the `ConfigureWorkflowApi` method, you can configure options, although

Workflow API Options also receive their initial settings from the configuration, allowing configuration

in `appsettings.json`.

### Security

To demonstrate the Workflow API Security component, this project includes authentication and authorization using JWT

Bearer, an authorization controller, and an in-memory SQLite database for storing user data.

To quickly get an API access token with all privileges, send a GET request to the auth controller with the

username `admin` and password `admin`.

The auth controller has a POST method allowing you to create a new user with any set of privileges. Privileges are

specified in dot format, such as `workflow-api.health`. You can learn more about privileges in

the [documentation](https://workflowengine.io/documentation/web-api/security) or use the convenient builder in

the `IWorkflowApiPermissions` service to get or validate a list of privileges.

The auth controller has a DELETE method to remove a user by their name.

It also has a GET method to get a user from the

database and create a list of claims for a JWT token based on their saved privileges.

This token is then generated

based on the JWT configuration and returned as a string.

### Client Generation

Using the `openapitools/openapi-generator-cli` tool hosted in Docker, a C# client code for Workflow API is generated.

This client is generated based on the `swagger.yaml` API specification. The client is essentially boilerplate code for

working with API endpoints. It includes DTO classes for models, code for forming request objects, request settings,

exception handling, creating an HTTP client, making requests, and data serialization and deserialization.

This tool can generate clients not only for C# but also for almost any popular language, such as TypeScript, Python, Go,

Java, and many others. To generate your client, you can open the [online Swagger editor](https://editor.swagger.io/),

upload the specification, and select `Generate Client → your language` from the menu. Alternatively, you can use the

client generation script in this repository and modify it to generate a client in an additional language.

### Testing

To run automated testing, you need to install and run Docker, then execute the following command:

```bash

pwsh ./Scripts/Tests/run-tests.ps1

```

The tests are integration tests and use Docker databases, and start web application hosts in a separate thread,

configuring them as needed for the tests. Each controller is tested in various use cases to ensure full coverage.

The tests also use an automatically generated client, so significant changes in the API specification will break the

application's build and help understand where backward compatibility is violated and where tests need to be modified.

#### Providers

By default, testing is conducted for all data providers supported by Workflow Engine:

- `Mongo`: MongoDB

- `Mssql`: Microsoft SQL Server

- `Mysql`: MySQL

- `Postgres`: PostgreSQL

- `Oracle`: Oracle

- `Sqlite`: SQLite

To change the list of providers for testing, you need to pass the `-Providers` parameter to the script with a list of

providers separated by commas (without spaces in parameter value). For example:

```bash

pwsh ./Scripts/Tests/run-tests.ps1 -Providers "Mongo","Mssql","Mysql","Postgres","Oracle","Sqlite"

```

Running tests for all providers can take a long time and require at least 24 GB of RAM. If you have less memory, you can

run tests for a specific provider or a subset of providers.