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

Procedure

1. In Fuse Online, in the left navigation panel, click Integrations.
2. 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 document that defines the REST API operations, upload the OpenAPI document.
   • If you need to define the OpenAPI document, select Create a new OpenAPI 3.x document or Create a new OpenAPI 2.x document.

5. Click Next.

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

     1. Click Review/Edit to open the API Designer editor.

     2. Review and edit as needed.

        Optionally, if your document uses the OpenAPI 2 specification, you can click Convert to OpenAPI 3 if you want the API Designer to convert your document to conform with the OpenAPI 3 specification.

     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 API Designer editor that Fuse Online opens:

     1. Define the OpenAPI document as described in Design and develop an API definition with API Designer.
     2. In the upper right, click Save, which closes the editor.
     3. Click Next.

Procedure

1. In the Operations list page, for the operation whose flow you want to define, 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 one of the return codes that you configure for the Provided API Return Path step that finishes the operation’s flow. Configure the return path step as follows:

   1. Under Default Response, in the Return Code field, accept the default response that Fuse Online displays, or click the down caret and scroll to select the default response that you want. The flow sends this response when execution of the operation flow does not return any of the configured error responses. Typically, the default response return code indicates a successful operation.

   2. Under Error Handling, indicate whether you want to include the error message in the body of the returned message.

      During development, you typically want to return the error message. In production, however, you might want to hide the error message if it contains sensitive or proprietary information. The error message is a JSON formatted string that contains responseCode, category, message, and error elements, for example:

         {
            responseCode: 404,
            category:  "ENTITY_NOT_FOUND_ERROR",
            message: "SQL SELECT did not SELECT any records"
            error: SYNDESIS_CONNECTION_ERROR
          }

      Note that during development, the most reliable way to know that an error happened is to check the HTTP_RESPONSE STATUS header in the response to the caller. You can also check the integration pod’s log for INFO messages. The integration’s Activity log shows a successful exchange and errors are not always visible in the Activity log.

   3. Under Error Response Codes, Fuse Online displays an entry for each error that a connection in the flow might return. For each error, accept the 200 All is good default return code or click to select another HTTP status return code.

      The return codes that you can select from, are the return codes that the OpenAPI document defines for the operation that this flow executes. If Fuse Online does not display a return code that you need, you can edit the OpenAPI document to add it.

      To do this, in the upper right, click View/Edit API Definition. Edit the OpenAPI document as needed. When you are done, save the OpenAPI document. Fuse Online returns to editing the Provided API Return Path and reflects any changes that you saved.

   4. Click Next to complete configuration of the return path.

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.

Procedure

1. Import the Task API quickstart integration:

   1. Go to https://github.com/syndesisio/syndesis-quickstarts/tree/1.11/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 the TaskAPI-export.zip file that you downloaded to the Import page. 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. Although the entry indicates that configuration is required, this integration is ready to publish.
2. Click Edit Integration to view the list of the operations that this API provides.

3. To examine the flows for each operation:

   1. Click its Edit flow button to display the visualization for that flow.

      Each flow already has a database connection, one or more data mapper steps, and a Provided API Return Path step that finishes the flow.

   2. For the Invoke SQL step, click Configure to see the SQL statement that the connection executes. Then click Cancel to return to that operation’s visualization flow.
   3. For a data mapper step, click Configure to see the mappings. Then click Cancel to return to the visualization.
   4. For the Provided API Return Path step, which is the last step in every operation’s flow, click Configure to see the HTTP return codes that the operation might send to the caller. Click Cancel to return to the visualization.
   5. After examining one operation’s flow, click the Integrations> Task API> Operation drop down menu and then select another operation.
   6. Repeat this subset of steps to examine each flow.
4. Click Save and edit the integration name if you want to.

5. Click Save and Publish.

   The summary page for the integration shows publication progress as it assembles, builds, deploys, and starts the integration.

6. 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-fuseonline.apps.openshift.com/

   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 enabled Red Hat 3scale discovery. This means that Red Hat 3scale controls access to the integration’s API and also publishes your API provider integration. To test the integration, open the 3scale dashboard to obtain the integration’s URL.

   If you do not want Red Hat 3scale to control access to the integration’s API, you can disable discovery. You do this in Fuse Online by viewing the integration’s summary page. On this page, click Disable discovery. Fuse Online republishes the integration and provides an external URL for invoking integration execution.

   You can enable or disable discovery for each API provider integration.

Procedure

1. In Fuse Online, in the left navigation panel, click Integrations.
2. In the Task API integration entry, click View to display the integration’s 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.

   export externalURL="https://i-task-api-fuseonline.apps.openshift.com"

5. Invoke a curl command that triggers execution of the flow for the Create new task operation:

   curl -k --header "Content-Type: application/json" --request POST --data '{"id":1, "task":"my first task :)!"}' $externalURL

   • -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 {"id":1, "task":"my new task!"}. Note that the completed field is not required.
   • $externalURL is the URL to invoke.

   This command sends an HTTP POST request to the Task API service, which triggers execution of the Create new 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":null,"id":1,"task":"my new task!"}

6. Invoke the following curl commands to create two more tasks:

   curl -k --header "Content-Type: application/json" --request POST --data '{"id":2, "task":"my second task :|"}' $externalURL
   
   curl -k --header "Content-Type: application/json" --request POST --data '{"id":3, "task":"my third task :("}' $externalURL

7. Invoke a curl command that triggers execution of the flow for the Fetch task by ID operation:

   curl -k $externalURL/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.

8. Invoke the following curl command that triggers execution of the flow for the Fetch all tasks operation:

   curl -k $externalURL

9. Optionally, invoke a curl command that triggers execution of the flow for the Delete task for ID operation:

   curl -k -X DELETE $externalURL/3

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