3장. Managing services

Procedure

1. To define the OpenAPI functions:

   1. Identify and access the OpenAPI specification files for the services you intend to invoke.

   2. Copy the OpenAPI specification files into your workflow service directory, such as <project_application_dir>/specs.

      The following example shows the OpenAPI specification for the multiplication REST service:

      Example multiplication REST service OpenAPI specification

      openapi: 3.0.3
      info:
        title: Generated API
        version: "1.0"
      paths:
        /:
          post:
            operationId: doOperation
            parameters:
              - in: header
                name: notUsed
                schema:
                  type: string
                required: false
            requestBody:
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/MultiplicationOperation'
            responses:
              "200":
                description: OK
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        product:
                          format: float
                          type: number
      components:
        schemas:
          MultiplicationOperation:
            type: object
            properties:
              leftElement:
                format: float
                type: number
              rightElement:
                format: float
                type: number

   3. To define functions in the workflow, use the operationId from the OpenAPI specification to reference the desired operations in your function definitions.

      Example function definitions in the temperature conversion application

      {
         "functions": [
           {
             "name": "multiplication",
             "operation": "specs/multiplication.yaml#doOperation"
           },
           {
             "name": "subtraction",
             "operation": "specs/subtraction.yaml#doOperation"
           }
         ]
      }

   4. Ensure that your function definitions reference the correct paths to the OpenAPI files stored in the <project_application_dir>/specs directory.

2. To access the defined functions in the workflow states:

   1. Define workflow actions to call the function definitions you added. Ensure each action references a function defined earlier.

   2. Use the functionRef attribute to refer to the specific function by its name. Map the arguments in the functionRef using the parameters defined in the OpenAPI specification.

      The following example shows about mapping parameters in the request path instead of request body, you can refer to the following PetStore API example:

      Example for mapping function arguments in workflow

      {
         "states": [
          {
            "name": "SetConstants",
            "type": "inject",
            "data": {
              "subtractValue": 32.0,
              "multiplyValue": 0.5556
            },
            "transition": "Computation"
          },
          {
            "name": "Computation",
            "actionMode": "sequential",
            "type": "operation",
            "actions": [
              {
                "name": "subtract",
                "functionRef": {
                  "refName": "subtraction",
                  "arguments": {
                    "leftElement": ".fahrenheit",
                    "rightElement": ".subtractValue"
                  }
                }
              },
              {
                "name": "multiply",
                "functionRef": {
                  "refName": "multiplication",
                  "arguments": {
                     "leftElement": ".difference",
                     "rightElement": ".multiplyValue"
                  }
                }
              }
            ],
            "end": {
              "terminate": true
            }
          }
        ]
      }

   3. Check the Operation Object section of the OpenAPI specification to understand how to structure parameters in the request.
   4. Use jq expressions to extract data from the payload and map it to the required parameters. Ensure the engine maps parameter names according to the OpenAPI specification.

   5. For operations requiring parameters in the request path instead of the body, refer to the parameter definitions in the OpenAPI specification.

      For more information about mapping parameters in the request path instead of request body, you can refer to the following PetStore API example:

      Example for mapping path parameters

      {
        "/pet/{petId}": {
          "get": {
            "tags": ["pet"],
            "summary": "Find pet by ID",
            "description": "Returns a single pet",
            "operationId": "getPetById",
            "parameters": [
              {
                "name": "petId",
                "in": "path",
                "description": "ID of pet to return",
                "required": true,
                "schema": {
                  "type": "integer",
                  "format": "int64"
                }
              }
            ]
          }
        }
      }

      Following is an example invocation of a function, in which only one parameter named petId is added in the request path:

      Example of calling the PetStore function

      {
        "name": "CallPetStore", 

      1

      
        "actionMode": "sequential",
        "type": "operation",
        "actions": [
          {
            "name": "getPet",
            "functionRef": {
              "refName": "getPetById", 

      2

      
              "arguments": { 

      3

      
                "petId": ".petId"
              }
            }
          }
        ]
      }

      1

      State definition, such as CallPetStore.

      2

      Function definition reference. In the previous example, the function definition getPetById is for PetStore OpenAPI specification.

      3

      Arguments definition. OpenShift Serverless Logic adds the argument petId to the request path before sending a request.

Procedure

1. Locate the OpenAPI specification file you want to configure. For example, substraction.yaml.
2. Convert the file name into a valid configuration key by replacing special characters, such as ., with underscores and converting letters to lowercase. For example, change substraction.yaml to substraction_yaml.

3. To define the configuration key, use the converted file name as the REST client configuration key. Set this key as an environment variable, as shown in the following example:

   quarkus.rest-client.subtraction_yaml.url=http://myserver.com

4. To prevent hardcoding URLs in the application.properties file, use environment variable substitution, as shown in the following example:

   quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

   In this example:

   • Configuration Key: quarkus.rest-client.subtraction_yaml.url
   • Environment variable: SUBTRACTION_URL
   • Fallback URL: http://myserver.com
5. Ensure that the (SUBTRACTION_URL) environment variable is set in your system or deployment environment. If the variable is not found, the application uses the fallback URL (http://myserver.com).

6. Add the configuration key and URL substitution to the application.properties file:

   quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

7. Deploy or restart your application to apply the new configuration settings.