Skip to main content
Feedback

Configuring OpenAPI connector

The OpenAPI feature allows you to add necessary configurations for Flow to create Types that work with the specified OpenAPI schema. On the OpenAPI configuration screen, configure the Security settings and Schema settings.

Security settings

OpenAPI includes security configurations for Basic authentication, OAuth 2.0, and OIDC in the schema for each endpoint. As a result, you must specify all necessary details in the schema. The current OpenAPI version simplifies the setup process by allowing you to configure these security settings directly in the connector setup. You can use these configurations instead of the x-Flow-identity declarations in the schema.

The API key security feature remains consistent across both versions, and you can provide the API key in the connector's configuration values to utilize accordingly.

note

To ensure successful requests, the Flow or the section of the Flow making the request must use the same security mechanism as the OpenAPI request.

Basic authentication

For Basic authentication, you can use the following methods:

  • User information URL method: This method requires a user information URL that the OpenAPI connector accesses to verify the validity of the provided Basic authentication credentials. Default user information values, such as first and last names, populate with default settings. In this case, they get set to the same value as the given Username. You can ignore all other inputs when using this approach.

  • Secured user Information URL method: This method works similarly to the OAuth 2.0 strategy. Provide a user information URL that is secured by Basic authentication and that returns information about the authenticated user. In this case,mapping operates by matching the property on the Flow user object with the property specified in the supplied input. For example, if the user information URL endpoint provides a forename, you can insert it into the First Name field to map it to the Flow user object's First Name attribute.

OAuth 2.0 authentication

When setting up authentication for the OpenAPI connector, the OAuth/OIDC Grant Type drop-down allows you to select between two grant types: Authorization Code (default) and Client Credentials.

  • Authorization Code: This is the default grant type, typically used for applications that require user authorization. It involves redirecting the user to an authorization server to obtain an authorization code, which is then exchanged for an access token. Provide a user information URL that returns user details, similar to the requirements in OpenAPI (legacy). Map the returned information to the properties of the Flow user object. Successful configuration requires all input fields. If required, you can map one returned value to multiple fields.

  • Client Credentials: This grant type is used when the application needs to authenticate itself rather than a user. It is ideal for server-to-server communication where user interaction is not required. Provide the Client ID and Client Secret in the connector configuration, and the OpenAPI step will use those credentials to make requests.

OIDC authentication

For OIDC authentication, specify a space-separated list of the required scopes. This list must include all scopes necessary for the endpoints configured in the schema table. Omitting any required scopes may lead to runtime errors when accessing an endpoint that requires a scope not included in the list.

The OAuth/OIDC Grant Type drop-down allows you to select between two grant types: Authorization Code (default) and Client Credentials. While using Authorization code it is mandatory to define the Scopes. Scopes are a mechanism for specifying the level of access that the client application is requesting from the resource owner (user). They define the permissions that the application will have when accessing the user's information and resources. The scopes are defined as a space separated list, for example: email profiler.

Schema settings

The Flow engine reads the schema at the specified URL and provides a table with one entry for each endpoint. The table allows you to establish a Flow type for a specific endpoint and assign a custom name to that Flow type Additional information, such as the HTTP method and path, helps you identify the endpoint configured in each row. The table specifies types for use with the OpenAPI step and replaces the use of x-Flow-type extensions in the OpenAPI schema.

You can define the name of a request and a response type for eligible endpoints when configuring the Save/Update Type OpenAPI requests (PUT/POST).

After completing the OpenAPI configuration, you can configure any GET endpoint to load data directly into a table.

Loading connector data into a table

Perform the following steps to configure GET endpoints to load data directly into a table:

  1. Go to the OpenAPI configuration section of your Flow application.
  2. Click Configure Table for the GET endpoint that you wish to configure to load data into a table.
  3. Define the list of items:
    • Object Return configuration: This section provides endpoints that return an object containing metadata and a list of items. For example, enter this property if the endpoint returns an object with a property named ‘items,’ which contains the list of items to display in the table.
    • Array Return configuration: Select the default root option if the endpoint returns an array of items directly.
  4. Map Flow names to endpoint parameters. In the properties section of the modal, map the Flow names for common parameters that the endpoint might expect to the actual names defined by the endpoint.

For example, if the endpoint uses verbose parameter names, enter these into the input fields to allow Flow to map between its concept of search or offset to the endpoint’s concept of query or startingOffset.

For a better understanding, refer to the OpenAPI schema for the endpoint:

"/crud/get-list":
    get:
      summary: Get an object by id
      operationId: GetList
      parameters:
        - description: An identifier
          in: query
          name: identifier
          required: false
          schema:
            type: string
        - description: A property to order by
          in: query
          name: order
          required: false
          schema:
            type: string
        - description: The direction to order by
          in: query
          name: directionOfOrder
          required: false
          schema:
            type: string
        - description: The number of results to return
          in: query
          name: numberOfResults
          required: false
          schema:
            type: string
        - description: The offset from the starting point of the results
          in: query
          name: startingOffset
          required: false
          schema:
            type: string
        - description: A query to filter the results by
          in: query
          name: query
          required: false
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
      security:
      - apiKey: []

  1. After you complete the configuration, load data directly into a table component by configuring the type and binding to load into the table.

Similar to file upload, you can find a binding for the given type that corresponds to a specific OpenAPI endpoint like this:

Special considerations

  • Schema URL changes: If you change the schema URL hosting location or the server URL while using the Code Value, you must reconfigure the settings. This issue occurs because schema configurations are specific to tenants and their respective schema URLs. Similarly, when multiple connectors use the same schema URL, they share the same schema configuration, which can lead to unintended consequences.

  • Schema availability: While we make efforts to cache the schema for runtime use, you must ensure that it remains available at the specified URL. Avoid sudden changes to the schema whenever possible, as they can cause issues. Alternatively, you can use the schema configured with Code Value instead.

  • Flow security: Secure any parts of Flow that make OpenAPI queries using methods other than API keys with the appropriate security measures. For example, by protecting an entire Flow with OAuth 2.0, you enable OAuth 2.0 requests to be made using the OpenAPI step.

File uploads

When a schema includes an endpoint that accepts a string formatted as binary or base64, the OpenAPI service automatically recognizes this as an endpoint capable of file uploads. You do not need to configure further services. Refer to the following screenshot for a sample file upload endpoint in an OpenAPI YAML schema.

"/crud/upload-binary":
    post:
      summary: Upload a file
      operationId: UploadFile
      requestBody:
          content:
            '*/*':
                schema:
                  type: string
                  format: binary
      responses:
        200:
          description: successful operation
      security:
      - apiKey: []

Configure the file upload component on your page and select the OpenAPI service along with the corresponding endpoint from the drop-down menu, as illustrated below:

The additional OpenAPI path drop-down displays only when you select an OpenAPI service from the 'The connector to load the files from' drop-down.

On this Page