Chapter 6. Creating an integration that is triggered by a REST API call

To trigger execution of an integration on demand, start the integration with a REST API service that you provide. Integrations that start this way are referred to as API provider integrations. An API provider integration allows REST API clients to invoke commands that trigger execution of the integration.

When Fuse Online publishes an API provider integration, any client with network access to the integration endpoints can trigger execution of the integration.

Note

If you are running Fuse Online on OpenShift Container Platform on-site, you can configure the Fuse Online server to enable Red Hat 3scale discovery of API provider integration APIs. By default, Fuse Online annotates an API provider integration’s API service definition for use with 3scale but does not expose those APIs for automatic 3scale discovery. Without 3scale discovery, there is no access control. With 3scale discovery, you can set access policies, centralize control, and provide high availability for your API provider integration APIs. For more information, see the API Gateway documentation that is available from the Red Hat 3scale documentation page.

See also: Configuring Fuse Online to enable 3scale discovery of APIs.

The following topics provide information and instructions for creating API provider integrations:

6.1. Benefit, overview, and workflow for creating API provider integrations

An API provider integration starts with a REST API service. This REST API service is defined by an OpenAPI 2.0 document that you provide when you create an API provider integration. After you publish an API provider integration, Fuse Online deploys the REST API service on OpenShift. The benefit of a API provider integration is that REST API clients can invoke calls that trigger execution of the integration.

Multiple execution flows

An API provider integration has multiple execution paths, referred to as flows. Each operation that the OpenAPI document defines has its own flow. In Fuse Online, for each operation that the OpenAPI document defines, you add connections and other steps to the execution flow for that operation. These steps process the data as required for the particular operation.

Example execution flow

For example, consider a human resources application that calls a REST API service that Fuse Online has made available. Suppose the call invokes the operation that adds a new employee. The operation flow that handles this call could:

  • Connect to an application that creates an expense report for new employee equipment.
  • Connect to a SQL database to add an internal ticket for setting up new equipment.
  • Connect to Google mail to send a message to the new employee that provides orientation information.

Ways to trigger execution

There are many ways to call the REST APIs that trigger integration execution, including:

  • A web browser page that takes data input and generates the call.
  • An application that explicitly calls the REST APIs, such as the curl utility.
  • Other APIs that call the REST API, for example, a webhook.

Ways to edit a flow

For each operation, you can edit its flow by:

  • Adding connections to the applications that need to process the data.
  • Adding steps between connections, including split, aggregate, and data mapping steps.
  • Altering the return code in the HTTP response that finishes the flow. The response goes to the application that invoked the call that triggered execution of the integration.

Workflow for creating an API provider integration

The general workflow for creating an API provider integration is shown in the following diagram:

General workflow for creating an API provider integration

Publishing an API provider integration

After you publish an API provider integration, in the integration’s summary page, Fuse Online displays the external URL for your REST API service. This external URL is the base URL that clients use to call your REST API services.

Testing an API provider integration

To test an API provider integration’s flows, you can use the curl utility. For example, suppose that the following curl command triggers execution of the flow for the Get Task by ID operation. The HTTP GET command is the default request so there is no requirement to specify GET. The last part of the URL specifies the ID of the task to get:

curl -k https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api/todo/1

6.2. How OpenAPI operations relate to API provider integration flows

An API provider integration’s OpenAPI document defines the operations that REST API clients can call. Each OpenAPI operation has its own API provider integration flow. Consequently, each operation can also have its own REST API service URL. Each URL is defined by the API service’s base URL and optionally by a subpath. REST API calls specify an operation’s URL to trigger execution of the flow for that operation.

Your OpenAPI document determines which HTTP verbs (such as GET, POST, DELETE and so on) you can specify in calls to your REST API service URLs. Examples of calls to API provider URLs are in the instructions for trying out the API provider quickstart example.

Illustration of an API provider integration example

The following diagram shows an API provider integration that processes data about people. An external REST API client invokes the REST API URLs that are deployed by the API provider integration. Invocation of a URL triggers execution of the flow for one REST operation. This API provider integration has 3 flows. Each flow can use any connection or step that is available in Fuse Online. The REST API along with its flows is one Fuse Online API provider integration, which is deployed in one OpenShift pod.

API provider integration with 3 flows

Editing the OpenAPI document while creating an API provider integration

After you specify an OpenAPI 2.0 document for your API provider integration, you can update the document as needed while you define the execution flows for the API operations. To do this, click View/Edit API Definition in the upper right of a page in which you are editing the API provider integration. This displays your OpenAPI document in the Apicurito editor. Edit and save the document to make changes that are reflected in Fuse Online.

Considerations while editing the OpenAPI document:

  • operationId properties for synchronization

    Synchronization between the versions of the OpenAPI document in the Apicurito editor and in the Fuse Online integration editor depend on a unique operationId property that is assigned to each operation that is defined in the document. You can assign a specific operationId property value to each operation, or use the one that Fuse Online generates automatically.

  • Request and response definitions

    In each operation’s definition, you can supply a JSON schema that defines the operation’s request and response. Fuse Online uses the JSON schema:

    • As the basis for the operation’s input and output data shapes
    • To display operation fields in the data mapper
  • No cyclic schema references

    A JSON schema for an API provider integration operation cannot have cyclic schema references. For example, a JSON schema that specifies a request or response body cannot reference itself as a whole nor reference any part of itself through intermediate JSON schemas.

6.3. Creating an API provider integration

To create an API provider integration, provide an OpenAPI document (.json, .yaml, or .yml file) that defines the operations that the integration can perform. Fuse Online creates an execution flow for each operation. Edit the flow for each operation to add connections and steps that process integration data according to the requirements for that operation.

Prerequisites

  • You are able to provide or define an OpenAPI document for the REST API operations that you want the integration to perform.

    To experiment, download the task-api.json file, which is an OpenAPI document for an API provider quickstart. You can upload this file when Fuse Online prompts you to provide an OpenAPI document.

  • You have a plan for the flow for each OpenAPI operation.
  • You created a connection for each application or service that you want to add to an operation’s flow.

Procedure

  1. In Fuse Online, in the left navigation panel, click Integrations.
  2. In the upper right, click Create Integration.
  3. On the Choose a connection page, click API Provider.
  4. On the Start integration with an API call page:

    • If you have an OpenAPI 2.0 document that defines the REST API operations, upload the OpenAPI document.
    • If you need to define the OpenAPI 2.0 document, select Create.
  5. Click Next.

    • If you uploaded a document, review or edit it:

      1. Click Review/Edit to open the Apicurito editor.
      2. Review and edit as needed.
      3. In the upper right, click Save or Cancel to close the editor.
      4. Click Next.
    • If you are creating a document, then in the Apicurito editor that Fuse Online opens:

      1. Define the OpenAPI document.
      2. In the upper right, click Save, which closes the editor.
      3. Click Next.

    For information about using the Apicurito editor, see Design and develop an API definition with API Designer.

Result

Fuse Online displays a list of the operations that the OpenAPI document defines.

Next step

For each operation, define a flow that executes that operation.

6.4. Creating the operation flows for an API provider integration

The OpenAPI document that defines your REST API service defines the operations that the service can perform. After you create an API provider integration, you can edit the flow for each operation.

Each operation has exactly one flow. In an operation flow, you can add connections to other applications and services, as well as steps that operate on data between connections.

As you add to operation flows, you might find that you need to update the OpenAPI document that the API provider integration is based on. To do this, click View/Edit API Definition in the upper right of a page in which you are editing your API provider integration. This displays your document in the Apicurito editor. In your OpenAPI definition, as long as each operation has a unique operationId property, you can save your updates in Apicurito and Fuse Online can synchronize the API provider integration’s flow definitions to have your updates.

Prerequisites

  • You created an API provider integration, gave it a name, and saved it.
  • You created a connection to each application or service that you want an operation flow to connect to. For details, see the information about creating connections.
  • Fuse Online is displaying the list of operations that the API defines.

Procedure

  1. In the Operations list page, for the operation whose flow you want to edit, click Create flow.
  2. For each connection that you want to add to this flow:

    1. In the flow visualization, click the plus sign to add a connection at that location.
    2. Click the connection that you want to add.
    3. Select the action that you want this connection to perform.
    4. Configure the action by entering data in the labeled fields.
    5. Click Next.

    Add all desired connections to the flow before you continue.

  3. In this operation flow, to process data between connections:

    1. In the flow visualization, click the plus sign where you want to add a step.
    2. Click the step that you want to add.
    3. Configure the step by entering data in the labeled fields.
    4. Click Next.

      For help, see Adding steps between connections.

    If you want to add another step that processes data between connections, repeat this subset of instructions.

  4. Map data to fields in the next connection:

    1. In the flow visualization, check for data type mismatch data mismatch icons, which indicate that the connection cannot process the incoming data. You need to add a data mapper step here.
    2. For each data mismatch icon in the flow visualization:

      1. Click the plus sign that is just before that step.
      2. Click Data Mapper.
      3. Define the needed mappings. For help, see Mapping integration data to fields in the next connection.
      4. Click Done to add the data mapper step to the flow.
  5. In the flow visualization, on the Provided API Return Path step, click Configure.

    Every API provider integration finishes each operation flow by sending a response to the REST API caller that triggered execution of the operation flow. The response contains the return code that is configured here.

    In this release, whenever an API call triggers execution of this flow, the return code is the code that is specified in this step. Error handling is expected to be supported in a future release.

    Accept the flow’s default return code, 501 Not implemented, or specify another return code as follows:

    1. Click in the Return Code input field, which displays a list of possible return codes.
    2. Scroll to the return code that you want and click it.
    3. Click Next.
  6. When this flow has all needed connections and steps and there are no data mismatch icons, or when you no longer want to edit the flow for now, do one of the following:

    • Publish — To start running the integration, in the upper right, click Publish. This builds the integration, deploys the REST API service to OpenShift, and makes the integration available to be executed. You can publish the integration each time that you complete the creation of an operation’s flow or each time that you edit an operation’s flow.
    • Save — To display the list of operations, in the upper right, click Save.
    • Operation — To switch to editing another operation’s flow, in the breadcrumbs at the top of the page, display the Operation dropdown and click the operation whose flow you want to edit. Fuse Online saves the current state of the flow you have been editing.

Repeat this procedure to edit another operation’s flow.

Next steps

When an API provider integration is running in Fuse Online on OpenShift Online or on OpenShift Dedicated, you can use the curl utility to confirm that it is working as expected. For examples of doing this, see the description of the API provider quickstart.

When an API provider integration is running in Fuse Online on OpenShift Container Platform, an administrator might have set the CONTROLLERS_EXPOSE_VIA3SCALE environment variable to true, which makes the integration’s API discoverable in Red Hat 3scale. When this environment variable is set to true, Fuse Online does not provide an external URL for an API provider integration. To test the integration, ask a 3scale administrator for guidance.

6.5. Configuring and publishing an example API provider quickstart integration

Fuse Online provides an API provider quickstart integration that you can import into your Fuse Online environment. This quickstart includes an OpenAPI document for a task management API. After importing the quickstart integration, you configure return codes, and then publish the integration. After you complete the procedure described below, the Task API integration is running and ready to be executed.

The API provider quickstart helps you quickly learn how to configure, publish, and test an API provider integration. But it is not a real-world example of how useful an API provider integration can be. For a real-world example, suppose that you already used Fuse Online to publish several simple integrations. You could define an OpenAPI document for triggering execution of those integrations. To do this, you would edit the flow for each OpenAPI operation to be almost the same as the simple integrations that you already published.

Prerequisites

  • Fuse Online is open in a browser.

Procedure

  1. Import the Task API quickstart integration:

    1. Go to https://github.com/syndesisio/syndesis-quickstarts/tree/1.6/api-provider and download TaskAPI-export.zip.
    2. In Fuse Online, in the left navigation panel, click Integrations.
    3. In the upper right, click Import.
    4. Drag and drop the TaskAPI-export.zip file that you downloaded. Fuse Online indicates that it has successfully imported the file.
    5. In the left navigation panel, click Integrations to see an entry for the Task API integration that you just imported. The entry indicates that configuration is required.
  2. Configure the Task API integration:

    1. Click the Task API entry to display the integration summary.
    2. In the upper right, click Edit Integration to display a list of the operations that this API provides.
    3. Update one step in the flow for the Create Task operation:

      1. In the POST entry for the Create Task operation, click Create flow to display the visualization for that flow.

        Connections and steps have already been added to this flow. In the operation flow visualization, to view the configuration for a step, click its Configure button. Click Cancel or Next to go back to the flow visualization. When you are done examining the configuration for one step, click Configure for another one to examine it. When you click a database connection, you can see the SQL statement that it executes.

      2. In the operation flow visualization, on the Provided API Return Path step, which is the last step in the flow, click Configure. You might have to scroll down to see it.
      3. Click in the Return Code input field and scroll to select 201 Created.
      4. Click Next.
      5. In the upper right, click Save.
    4. Update one step in the flow for the Delete Task for ID operation:

      1. In the DELETE entry for the Delete Task for ID operation, click Create flow to display the visualization for that flow.

        This operation flow has a data mapper step and a connection to the sample database that is provided with Fuse Online. In the operation flow visualization, click Configure on the database connection to view the SQL statement that it executes.

      2. Click Next or Cancel.
      3. In the operation flow visualization, on the Provided API Return Path step, which is the last step in the flow, click Configure.
      4. Click in the Return Code input field and scroll to select 200 OK.
      5. Click Next.
      6. In the upper right, click Save.
    5. Update one step in the flow for the Get Task by ID operation:

      1. In the GET entry for the Get Task by ID operation, click Create flow to display the visualization for that flow.

        This operation flow has two data mapper steps, a connection to the sample database that is provided with Fuse Online, and a log step.

      2. In the operation flow visualization, click Configure on a step to view its configuration. When you are done examining the configuration, click Next or Cancel. Do this for as many steps as you want.
      3. In the operation flow visualization, on the Provided API Return Path step, which is the last step in the flow, click Configure.
      4. Click in the Return Code input field and scroll to select 200 OK.
      5. Click Next.
  3. In the upper right, click Publish, and then Save and publish.

    Fuse Online displays the summary page for this integration and shows publication progress as it assembles, builds, deploys, and starts the integration.

  4. When the Task API integration summary page displays Running, Fuse Online displays the external URL for the Task API service. It looks something like this:

    https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api/

    This is where Fuse Online makes the Task API service available. REST API calls specify URLs that start with this base URL.

    If you are using Fuse Online on OpenShift Container Platform, if the external URL is not on the integration’s summary page, then an administrator has set the CONTROLLERS_EXPOSE_VIA3SCALE environment variable to true. To test this API provider integration, ask a 3scale administrator for guidance.

6.6. Testing the example API provider quickstart integration

When the Fuse Online Task API quickstart integration is running, you can invoke curl utility commands that send HTTP requests to the Task API service. How you specify the HTTP request determines the flow that the call triggers.

Prerequisites

  • Fuse Online indicates that the Task API integration is Running.
  • If your Fuse Online environment is running on OCP, Fuse Online is not configured to expose APIs to 3scale.

Procedure

  1. In Fuse Online, in the left navigation panel, click Integrations.
  2. Click the Task API integration to display its summary.
  3. Copy the integration’s external URL.
  4. In a terminal, invoke a command such as the following to assign the integration’s external URL to the externalURL environment variable. Be sure to replace the URL in this sample command with the URL that you copied and add /api to the end.

    export externalURL="https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api"`
  5. Invoke a curl command that triggers execution of the flow for the Create Task operation:

    curl -k --header "Content-Type: application/json" --request POST --data '{ "task":"my new task!"}' $externalURL/todo
    • -k allows curl to proceed and operate even for server connections that are otherwise considered insecure.
    • --header indicates that the command is sending JSON format data.
    • --request specifies the HTTP POST command, which stores data.
    • --data specifies the JSON format content to be stored. In this example the content is { "task":"my new task!"}.
    • $externalURL/todo is the URL to invoke.

      This command sends an HTTP POST request to the Task API service, which triggers execution of the Create Task operation’s flow. Flow execution adds a new task to the sample database and returns a message such as the following to indicate what it did:

    {"completed":false,"id":1,"task":"my new task!"}
  6. Invoke a curl command that triggers execution of the flow for the Get Task by ID operation:

    curl -k $externalURL/todo/1

    To obtain a task, the curl command needs to specify only the URL. The HTTP GET command is the default request. The last part of the URL specifies the ID of the task to get.

  7. Invoke a curl command that triggers execution of the flow for the Delete Task for ID operation:

    curl -k -X DELETE $externalURL/todo/1

    This command invokes the HTTP DELETE command with the same URL as the command that obtained a task by its ID.