Modeling Guide

OpenAPI Client

The OpenAPI client operator is a convenient client that is suitable for invoking services described in a swagger/openAPI document. However, its use is not limited to those services described in swagger/openAPI described.

This client is expected to be configured with some default parameters, such as method, pathPattern, produces, consumes, and security setting, to invoke remote services. These properties can be customized per call when the corresponding headers of the input message are set accordingly.

Parameters defined for the operation such as header, path, query, form, and file parameters can be set in the message headers using header names in form openapi.type_params.name, where type indicates one of the parameter types and name identifies the parameter name, respectively.

In other words, headers openapi.header_params.name, openapi.path_params.name, openapi.query_params.name, openapi.form_params.name, and openapi.file_params.name are used to represent the corresponding name parameter for the operation. Parameter values are interpreted as string for scalar values and set to the corresponding parameters of the request message except for file parameters. The value of a file parameter can be set either to the path to a file or to the content of a file.

For example, to assign file "/opt/pictures/dog12.png" or its content to file parameter "foto", header openapi.file_params.foto can be set to "/opt/pictures/dog12.png". Alternatively, this header can be set to the base64 representation of the content of this file while setting another parameter openapi.file_params.foto#name to its name "dog12.png" to indicate that the value of this file parameter is the content and not the file path. Parameters values for vector values are represented as arrays. All parameters except for the header parameters support vector values (e.g., ["sunny", "day"] for two values "sunny" and "day").

In addition to the above parameters, if header message.request_id is set in the input message, this header will be included in the output message so that each response message can be correlated to its corresponding request message. Furthermore, the status code is set in openapi.status_code in the output message.
Recognized Message Headers

Header

Description

message.request.id

The ID for correlating a request and its response messages.

openapi.header_params.x

Header parameter x.

openapi.path_params.x

Path parameter x.

openapi.query_params.x

Query parameter x.

openapi.form_params.x

Form parameter x.

openapi.file_params.x

File parameter x, where its value may represent the path to the file or the base64 encoded content of the file.

openapi.file_params.x#name

File name parameter for file parameter x, if set, represents the file name and the value of its file parameter represents the base64 encoded content.

openapi.path_pattern

Overrides the default pathPattern parameter configured at the .

openapi.method

Overrides the default method parameter configured at the operator.

openapi.produces

Overrides the default produces parameter (i.e., the accepted response content types) configured at the operator.

openapi.consumes

Overrides the default consumes parameter (i.e., the request content type) configured at the operator.

openapi.auth_scheme

Overrides the default authScheme parameter configured at the operator.

openapi.user

Overrides the default user configured at the operator.

openapi.password

Overrides the default password configured at the operator.

openapi.api_key_name

Overrides the default apiKeyName configured at the operator.

openapi.api_key_value

Overrides the default apiKeyType configured at the operator.

Several authentication schemes are supported by the OpenAPI client operator. These include basic, APIKey, and OAuth authentication schemes. When OAuth is chosen and its oauth2Flow is set to accessCode or implicit, the user must use the UI option of the OpenAPI client operator to authorize the client instance so that it can retrieve an access token. In this case, the correct redirection URL for this client instance must be registered at the authorization provider. The redirection URL has the service path /service/v1/runtime/internal/redirect.

You can use this operator as is, on its own, by manually configuring its parameters and using a custom operator that forwards appropriate input messages to this operator. If you have a swagger file, you can generate such custom operator and a demo graph using the generateOpenAPIClient REST operation of the engine. Refer to the API document (swagger.yaml) available at the installed vflow instance for details.

Configuration Parameters

Parameter

Type

Description

host

string

The service's host optionally including the port

Default: localhost:8090

schemes

string

The transport protocols.

Default: http

basePath

string

The service's base path.

Default: /service

pathPattern

string

The path pattern with optional path variables. Overridden by header openapi.path\_pattern.

Default: ""

method

string

The method name. Overridden by header openapi.method.

Default: "GET"

produces

string

A comma-separated list of media types that can be produced by the operation. Overridden by header openapi.produces.

Default: "application/json"

consumes

string

A comma-separated list of media types that can be consumed by the operation. Overridden by header openapi.consumes.

Default: ""

includeResponseHeaders

string

A comma-separated list of response header names that should be included in the output message. Overridden by header openapi.include\_response\_headers.

Default: ""

authScheme

string

The security scheme. The possible values are "", "basic", "apiKey", "oauth2". Overridden by header openapi.auth\_scheme.

Default: ""

user

string

The user name used by "basic" security scheme. Overridden by header openapi.user.

Default: ""

password

string

The password used by "basic" security scheme. Overridden by header openapi.user.

Default: ""

apiKeyName

string

The api key name used by "apiKey" security scheme. Overridden by header openapi.api\_key\_name.

Default: ""

apiKeyType

string

The api key type used by "apiKey" security scheme. The possible values are "header" or "query". Overridden by header openapi.api\_key\_type.

Default: ""

apiKeyValue

string

The api key value used by "apiKey" security scheme. Overridden by header openapi.api\_key\_value.

Default: ""

oauth2Flow

string

The flow used by "oauth2" security scheme. The possible values are "implicit", "password", "application", "accessCode".

Default: ""

oauth2TokenUrl

string

The token url used by "oauth2" security scheme" when the flow is set to "password", "application", or "accessCode".

Default: ""

oauth2AuthUrl

string

The authorization url used by "oauth2" security scheme when the flow is set to "implicit" or "accessCode".

Default: ""

oauth2ClientId

string

The client ID used by "oauth2" security scheme".

Default: ""

oauth2ClientSecret

string

The client secret used by "oauth2" security scheme".

Default: ""

oauth2AdditionalHeaders

string

Optional headers added in a token request, given as \{"header1": "value", ...\}.

Default: ""

useCsrfToken

bool

If set to true, the client automatically retrieves a csrf-token at its first request and uses it in its subsequent requests.

Default: false

tlsCertificate

string

The file path to the TLS certificate file.

Default: ""

tlsKey

string

The file path to the TLS private key file.

Default: ""

tlsCa

string

The file path to the TLS certificate authority file.

Default: ""

tlsSkipVerify

bool

If set to true, the client does not verify the server's certificate chain nor the host name.

Default: false

maxConcurrency integer The maximum number of concurrent requests that are handled per operator instance. If the message order must be preserved, set this value to 1.

Default: 8

Input

Input

Type

Description

in

message

Input message where parameters are set in the headers and the optional content in body.

Output

Output

Type

Description

out

message

Output message where parameters are set in the headers and the optional content in body.