Menu Close

Red Hat Training

A Red Hat training course is available for Red Hat Fuse

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 an 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 Start 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 from scratch.
  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 and go to step 6 in this procedure.
    • 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 Designing and developing an API definition with Apicurito.

  6. Enter a name and description for your integration and click Save and continue. You are ready to define a flow for each 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, click the entry for an operation whose flow you want to edit.
  2. Add all desired connections to this flow. For each connection that you want to add:

    1. In the flow visualization panel on the left, click the plus sign where you want to add a connection.
    2. On the Choose a Step page, click the connection that you want to add to this flow.
    3. Click the action that you want this connection to perform.
    4. Configure the action by entering data in the labeled fields.
    5. Click Done.
    6. In the upper right, click Save.

    For each connection that you want to add to this flow, repeat this subset of instructions. 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 panel on the left, click the plus sign where you want to add a step.
    2. On the Choose a Step page, click the step that you want to add.
    3. Configure the step by entering data in the labeled fields.
    4. Click Done.
    5. In the upper right, click Save.

      For help, see Adding steps between connections.

    Repeat this subset of instructions to add another step that processes data between connections.

  4. In the flow visualization panel on the left, 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. Go back to the previous subset of instructions. On the Choose a Step page, click Data Mapper, and define the needed mappings. For help, see Mapping integration data to fields in the next connection.
  5. In the flow visualization panel on the left, at the bottom, hover over the Provided API Return Path icon to see that it is the Provided API Return Path.

    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 specified 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, 200 OK, or specify another return code as follows:

    1. Click the Provided API Return Path icon.
    2. Click in the Return Code input field, which displays a list of possible return codes.
    3. Scroll to the return code that you want and click it.
    4. Click Next.
  6. When this flow has all needed connections and steps, 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.
    • Edit another flow - To edit the flow for another operation, select it from the Operations drop-down list, which is at the top of the page, and looks something like this:

      operations

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. To 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. To 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. To configure the flow for the Create Task operation:

      1. Click the POST entry for the Create Task operation to display a page that prompts you to add to the integration.

        Connections and steps have already been added to this flow. In the operation flow visualization panel on the left, move your cursor over the icons to see what they represent. Click a step to view its configuration. When you are done examining one, click 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 panel on the left, click the Provided API Return Path icon at the bottom. You might have to scroll down to see it. When you hover over it, Fuse Online displays Provided API Return Path.
      3. If you need to, scroll up on the right, click in the Return Code input field and scroll to select 201 Created.
      4. Click Next.
      5. In the upper right, click Save.
      6. At the top, to the right of Operations, click the down arrow and then click Go to Operations List.
    4. To configure the flow for the Delete Task for ID operation:

      1. Click the DELETE entry for the Delete Task for ID operation to display a page that prompts you to add to the integration.

        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 panel, click the database connection to view the SQL statement that it executes.

      2. In the operation flow visualization panel, click the Provided API Return Path icon at the bottom.
      3. Click in the Return Code input field and scroll to select 200 OK.
      4. Click Next.
      5. In the upper right, click Save.
    5. To configure the flow for the Get Task by ID operation:

      1. At the top of the page, to the right of Operations, click the down arrow and then click Get Task by ID.

        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 panel, click an icon for a step or connection to view its configuration. When you are done examining one, click another one.
      3. In the operation flow visualization panel, click the Provided API Return Path icon at the bottom.
      4. Click in the Return Code input field and scroll to select 200 OK.
      5. Click Next.
  3. In the upper right, click Publish.

    Fuse Online displays the integrations list page and shows publication progress as it assemblies, builds, deploys, and starts the integration.

  4. When the entry for the Task API integration displays Running, click the entry to display the summary page for the integration, which provides 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.