Chapter 9. Trigger integration execution with a REST API call

1. On the Choose a Start Connection page, click the API Provider card.

2. On the Start integration with an API call page, upload a file that contains an OpenAPI 2.0 schema or indicate that you want to create the schema now. If you upload a file, you can review and edit it. If you select Create from scratch, Fuse Online opens an editor that supports creation of OpenAPI schemas.

   Caution

   After you save or publish an API provider integration, you cannot update the OpenAPI definition for the REST API service. If you need to edit the OpenAPI definition then you must start over and create a new API provider integration.

3. Give the integration a name and save it.

4. On the Choose operation page, for each operation that the OpenAPI schema defines, create the integration flow for that operation:

   1. Click an operation to display the Add to Integration page.
   2. Add the connections that are required to implement the selected operation.
   3. Add additional steps that process data between connections. For example, in the visual representation of this integration flow, check for data type mismatch indications. For each data type mismatch, add a step that maps data fields.

   4. In the visual representation of this integration flow, click the flow’s finish connection and specify a return code. When Fuse Online executes this integration flow and reaches this connection, Fuse Online sends the return code to your API service, which in turn sends a response to the caller that invoked the API that triggered the integration.

      In this release, because an API provider integration is a Technology Preview feature, the integration flow always returns the code that you select. Error handling is not yet supported.

5. Publish the integration.

   Fuse Online provides the URL where your REST API service is available.

6. Optionally, use the curl utility to test the integration flows.

   For example, suppose that the following curl command triggers execution of an integration 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

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 the API Provider card.

4. On the Start integration with an API call page, if you have an OpenAPI 2.0 schema that defines the REST API operations then upload it in one of the following ways:

   • Drag and drop the file that contains the schema.
   • Click Choose File to navigate to and select the file that contains the schema.
   • Click Use a URL and enter the URL for the schema.

   Or, if you need to define the schema, select Create from scratch.

5. Click Next.

   • If you uploaded a schema, remember that this is your only opportunity to change it. To review or edit the schema:

     1. Click Review/Edit to open the Apicurio 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 schema from scratch then in the Apicurio editor that Syndesis opens:

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

   For information about using the Apicurio editor, see Design and develop an API definition with Apicurito. In this Technology Preview release, you cannot edit the operation description that will appear in the operations list in Fuse Online.

6. On the Give this integration a name page, enter a name for your integration.
7. Optionally, enter a description that helps you distinguish this integration from other integrations.
8. Click Save and continue to display the Choose Operation page. You are ready to define a flow for each operation.

Procedure

1. In the Choose operation page, click the entry for an operation whose flow you want to edit. This opens the Add to Integration page.

2. In the integration visualization panel on the left, click the icon at the bottom. When you hover over this icon, Provided API Return Path appears.

   Every API provider integration ends each integration flow by sending a response to the REST API caller that triggered execution of the integration flow.

3. Specify the operation’s return code as follows:

   1. In the Provided API Return Path page, click in the Return Code input field, which displays a list of possible return codes.

   2. Scroll to 200 OK and click it.

      If there is a return code that better describes the result then you can select that one instead. However, in this Technology Preview release, you can select only one return code. Whenever an API call triggers execution of this integration flow, this is the return code. This Technology Preview release does not support error handling.

   3. Click Done.

   4. In the upper right, click Save as Draft.

      After you implement the return code for at least one operation, you can publish the integration to start running it. When it is running, you can invoke an API call that triggers execution of the integration flow for which you defined the return code. However, you probably want to add more steps to the operation’s flow.

4. In this integration flow, to connect to another application or service:

   1. In the integration flow visualization panel on the left, hover over the plus sign in the location where you want to add a connection and in the popup that appears, click Add a connection.
   2. Click the connection that you want to add to this integration flow.
   3. Click the action that you want this connection to perform.
   4. Configure the action.
   5. Click Done.
   6. In the upper right, click Save as Draft.

   For each connection that you want to add to this integration flow, repeat this subset of instructions. Add all desired connections to the integration flow before you continue.

5. In this integration flow, to process data between connections:

   1. In the integration flow visualization panel on the left, hover over the plus sign in the location where you want to add a step and in the popup that appears, click Add a step.
   2. In the Choose a Step page, click the step that you want to add.
   3. Configure the step.
   4. Click Done.

   5. In the upper right, click Save as Draft.

      For help, see Adding steps between connections.

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

6. In the integration 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 Map integration data fields to the next connection in the integration.

7. When this integration flow has all needed connections and steps, do one of the following:

   • To start running the integration, in the upper right, click Publish. This builds the integration and makes it available to be executed. You can publish the integration each time that you complete the creation of an operation’s integration flow or each time that you edit an operation’s integration flow.
   • To edit the integration flow for another operation, in the upper right, click Go to Operations List.

Procedure

1. To import the Task API quickstart integration:

   1. Go to https://github.com/syndesisio/syndesis-quickstarts/tree/master/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 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 integration flow for the Create Task operation:

      1. Click the Create Task entry to display a page that prompts you to add a connection or add a step.

         Connections and steps have already been added to this integration flow. In the integration flow visualization panel on the left, move your cursor over the icons to see what they represent. Click a step or connection 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 integration 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. Click in the Return Code input field and scroll to select 201 Created.
      4. Click Done.
      5. In the upper right, click Save as Draft and then Go to Operation List.

   4. To configure the integration flow for the Delete Task for ID operation:

      1. Click the Delete Task for ID entry to display a page that prompts you to add a connection or add a step.

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

      2. In the integration 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 Done.
      5. In the upper right, click Save as Draft and then Go to Operation List.

   5. To configure the integration flow for the Get Task by ID operation:

      1. Click the Get Task by ID entry to display a page that prompts you to add a connection or add a step.

         This integration flow has two data mapper steps, a connection to the sample database that is provided with Fuse Online, and a log step. In the integration flow visualization panel, click an icon for a step or connection to view its configuration. When you are done examining one, click another one.

      2. In the integration 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 Done.

3. In the upper right, click Publish.

   Fuse Online displays the integration summary page and shows publication progress as it assemblies, builds, deploys, and starts the integration. The integration summary page also provides the external URL for the API provider service, which 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.

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

   export externalURL="https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api"

5. Invoke a curl command that triggers execution of the integration 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 integration flow. The integration flow 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 integration 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 integration 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.