Configuring OpenAPI Services Endpoints

This document describes how you can configure OpenAPI service endpoints in SonataFlow.

Overview

SonataFlow leverages MicroProfile REST Client to invoke OpenAPI services. Therefore, you can configure the OpenAPI services by following the MicroProfile Config specification. For the list of properties to configure in the MicroProfile REST Client specification, see Support for MicroProfile Config in MicroProfile REST Client documentation.

SonataFlow follows the strategy defined in the kogito.sw.operationIdStrategy property to generate the REST Client. The possible values of the kogito.sw.operationIdStrategy property include:

  • FILE_NAME(Default value): SonataFlow uses the configuration key based on the OpenAPI document file name as shown in the following example:

    Example property
    quarkus.rest-client.stock_portfolio_svc_yaml.url=http://localhost:8282/

    In the previous example, SonataFlow uses stock_portfolio_svc_yaml as configuration key as the OpenAPI document is available at src/main/resources/openapi/stock-portfolio-svc.yaml.

  • FULL_URI: SonataFlow uses the full URI path as configuration key as shown in the following example:

    Example Serverless Workflow
    {
    "id": "myworkflow",
    "functions": [
        {
          "name": "myfunction",
          "operation": "https://my.remote.host/apicatalog/apis/123/document" (1)
        }
    ]
    ...
}
    1 URI path of the OpenAPI document
    Example property
    quarkus.rest-client.apicatalog_apis_123_document.url=http://localhost:8282/

    In the previous example, SonataFlow uses apicatalog_apis_123_document as configuration key.

  • FUNCTION_NAME: SonataFlow uses the workflow ID and the function name that references the OpenAPI document as shown in the following examples:

    Example Serverless Workflow
    {
    "id": "myworkflow",
    "functions": [
        {
          "name": "myfunction",
          "operation": "https://my.remote.host/apicatalog/apis/123/document"
        }
    ]
    ...
}
    Example property
    quarkus.rest-client.myworkflow_myfunction.url=http://localhost:8282/

    In the previous example, SonataFlow uses "myworkflow_myfunction" as configuration key.

  • SPEC_TITLE: SonataFlow uses the value of info.title in the OpenAPI document as shown in the following examples:

    Example OpenAPI document
    ---
openapi: 3.0.3
info:
  title: stock-service API
  version: 2.0.0-SNAPSHOT
paths:
  /stock-price/{symbol}:
...
    Example property
    quarkus.rest-client.stock-service_API.url=http://localhost:8282/

    In the previous example, SonataFlow uses stock-service_API as configuration key.

A Kubernetes service endpoint can be used as a service URL if the target service is within the same cluster, such as http://myservice.mynamespace.cluster.svc.local.

Using URI alias

As an alternative to kogito.sw.operationIdStrategy, you can assign an alias name to a URI by using workflow-uri-definitions custom extension. Then you can use that alias as configuration key and in function definitions.

Example workflow
"extensions" : [ {
      "extensionid": "workflow-uri-definitions",
      "definitions": {
        "remoteCatalog": "https://my.remote.host/apicatalog/apis/123/document",
       }
     }
  ],
  "functions": [
        {
          "name": "operation1",
          "operation": "remoteCatalog#operation1"
        },
        {
          "name": "operation2",
          "operation": "remoteCatalog#operation2"
        }
    ]
Example property
quarkus.rest-client.remoteCatalog.url=http://localhost:8282/

In the previous example, SonataFlow uses remoteCatalog as configuration key.

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!