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

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.

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 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 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 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:

     

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 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 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 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.

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.