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

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

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.

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.