Creating Your First REST API

High-Level Steps in the Tutorial

The high-level steps for creating and configuring the app in this tutorial are as follows:

1. Create a new app
2. Create a JSON schema to reuse it across your app. The JSON schema describes the format of the JSON data used in the tutorial. In this tutorial, we use a simple JSON schema for the request that the REST service receives and the response that the service sends back. You can specify the JSON schema directly or specify JSON data which is converted to JSON schema automatically.
3. Create a flow and add a REST trigger (Receive HTTP Message)
4. Map trigger output to flow input. This is the bridge between the trigger and the flow where the trigger passes on the request data to the flow input.
5. Map flow output to trigger reply. This is the bridge between the flow output and the response that the trigger sends back to the HTTP request it received. After the flow has finished executing, the output of the flow execution is passed back to the trigger by the Return activity. Hence, we map the flow output to the trigger reply. This mapping is done in the trigger configuration.
6. Add a LogMessage activity to the flow and configure a message that the activity must log in the logs for the app as soon as it receives a request.
7. Add the first branch to check whether the passenger’s last name is Jones to return the information of a flight booked in Business class for Jones.
8. Add a second branch to process any other passengers and return the information of a flight booked in Economy class if the last name is not “Jones”.
9. Validate the app to ensure that there are no errors or warnings in any flows or activities.
10. Build the app
11. Test the app

Step 1: Create a new app

Tip: To watch this step in the video tutorial, click

To create a new Flogo app in Flogo Enterprise:

1. Click Apps.

   If this is your first app, a blank screen appears suggesting that you need to create or import a new app. If you have already created apps earlier, the apps are displayed on this screen.

   

2. Click Create/Import app.

   Flogo Enterprise creates an app with a default name in the New_Flogo_App_<sequential_app_number> format.

3. Click the default app name to make it editable. Change the app name to FlightApp and click anywhere outside the name to save the changes made to the name.
   

   

Step 2: Create a JSON schema to reuse it across your app

Tip: To watch this step in the video tutorial, click

1. Copy the following JSON sample to use it in your app: 

{
"Class" : "string",
"Cost" : 0,
"DepartureDate" : "2017-05-27",
"DeparturePoint" : "string",
"Destination" : "string",
"FirstName" : "string",
"Id" : 0,
"LastName" : "string"
}

Note: Ensure you use straight quotes when entering the schema elements and values.
2. On the Apps page, in the Flows section, click Schemas.



3. In the Schemas dialog box that opens, click Schema to add a new JSON schema.



4. Name your schema as FlightResponse and paste the copied schema into the text editor. Alternatively, if you enter JSON data in the editor, the JSON data is automatically converted to JSON schema.



5. Click Save.

Step 3: Create a flow and add a REST trigger (Receive HTTP Message)

Tip: To watch this step in the video tutorial, click

Every app must have at least one flow and, in most cases, a trigger that initiates the flow. Create a new flow with the REST trigger. The ReceiveHTTPMessage REST trigger listens for an incoming REST request that contains the details of a passenger who wants to book a flight. Specify the fields for the request in the REST trigger in JSON schema format.

To create a flow:

1. On the Flows page, click Create .


The Add triggers and flows dialog box is displayed. The Flow option is selected by default.

2. In the Flow details section, provide the following details and click Create:
   Name: FlightBookings
   Description : Optional description of the flow

   

3. In the dialog box that appears, click Start with a trigger.

   

4. In the Triggers catalog, click Receive HTTP Message.

   

5. In the Configure trigger: ReceiveHTTPMessage dialog box:

   

   1. Select GET as the Method.
   2. Enter /flightbookings in the Resource path box.
   3. Enable the Use App Level Schema toggle next to Response Schema to open the Schemas dialog box and select the FlightResponse schema you defined earlier.

   The schema you select automatically appears in the Response Schema box.

   4. Click Continue.
6. Select Copy Schema when prompted as shown in the following image.

   

   The schema that you entered when creating the trigger is automatically copied to the Flow Inputs & Outputs tab to match the input and output of the trigger.

   A new flow is created and attached to a REST trigger.

   Your flow should look similar to the following:

   

7. Collapse the Flow Inputs & Outputs tab.

Step 4: Map trigger output to flow input

Tip: To watch this step in the video tutorial, click

When Flogo Enterprise receives a request from a passenger (a REST request), the data from the request is output by the ReceiveHTTPMessage REST trigger. For the request to be processed, this output must be used by the flow in the form of flow input. Hence, you must map the trigger output to the flow input.

To do this:

1. Click the REST trigger icon to open its configuration dialog box.



In the configuration dialog box, multiple tabs are displayed in a column on the left. Trigger Settings is selected by default.

2. Click Output Settings to add the query parameter.

3. Click Add row to add a new query parameter.

   

4. In the new row that appears in the Query Parameters table, enter the value of ParameterName as lastname and click Save in the same row (in the Action column).

   

5. To start the mapping, click the Map to Flow Inputs tab and configure the mapping of the trigger output. On the Map to Flow Inputs tab, the Flow Input section is displayed. This is the list of flow inputs that can be mapped to the trigger outputs. Only headers are displayed in the flow inputs. The new query parameter is not visible yet.
   
   
   

6. Click Sync to display the new values. Now, queryParams should appear in the Flow Input column.
   
   
   

7. In the Flow Input section, click headers.

   The headers box on the right of Flow Input appears empty to begin with.

   

8. Map the trigger output headers to the flow input header:

   1. Expand $trigger to see all the trigger outputs available.
      This displays the headers and body.
      
   2. To map the Trigger Output headers to the Flow Input headers, in the Trigger Output section, click $trigger and then click headers.
      The box should now display $trigger.headers. This indicates that you have successfully mapped the trigger output headers to the flow input header.
      
      
9. To map the flow input, in the Flow Input section, click queryParams .

   

   The data mapper view is the same as the one while mapping headers. The queryParams text editor appears empty to begin with.

10. To map the flow input queryParams with the trigger output queryParams, in the Trigger Output section, click $trigger and then click queryParams.
    The box should now display $trigger.queryParams. This indicates that you have successfully mapped the trigger output queryParams to the flow input queryParams.

    

11. Click Save to save your progress.

    This completes the mapping of flow inputs.

Step 5: Map flow output to trigger reply

Tip: To watch this step in the video tutorial, click

When the execution of the flow is completed, the output must be sent back to the trigger for the trigger to send a reply to the REST request initiator. Hence, the flow output data must be mapped to the trigger reply, which then returns the result of the flow execution to the REST request initiator.

To map the flow output to the trigger reply:

1. In the left pane, click the Map from Flow Outputs tab to configure the mapping of the trigger reply. A Trigger Reply column is displayed in the right pane. You can map the following trigger replies to the flow outputs - code and data.



2. In the Trigger Reply section: 

   1. To map code, click code. The code text editor appears empty on the right of your Trigger Reply section.
      The Flow Output section displays the data available for the mapping. $flow should appear in this section. To see all the flow outputs available for the mapping, expand $flow. This displays code and data.
      The Functions section displays functions available for mapping.
   2. In the Flow Output section, under $flow, click code.
      $flow.code should now appear in the code text editor. You have successfully mapped the Trigger Replycode to the Flow Outputcode.
      
      

3. Repeat the same steps to map Trigger Reply data to Flow Output data.
   

4. Note: You can expand data in both the Trigger Reply section and the Flow Output section to see the tree structure of the data you have defined in schemas.

5. Click Save and close the trigger dialog box.
   The blank flow with mappings is created and should look like this:
   

Step 6: Add a Log Message activity to the flow

Tip: To watch this step in the video tutorial, click

The flow uses the LogMessage activity to log an entry in the app logs when the trigger receives a request from the passenger that reaches the trigger in the form of a REST request.

To add a LogMessage activity:

1. On the right of the Flow Inputs & Outputs tab, click .

2.   In the Add Activity page, go to the General tab and click Log Message.



The LogMessage activity’s configuration window opens automatically after its creation. By default, the Settings tab is selected.



3. To configure the LogMessage activity with a message to log when it receives an incoming request from the ReceiveHTTPMessage trigger:
   1. Click the Input tab. An Activity Input column is displayed on the right side of the LogMessage activity’s tabs. This column lists the activity inputs. In the Activity Input column, message appears highlighted in red as the configuration of this activity input is mandatory.

   

   2. Click message to open the mapper to the right. In the mapper, you must configure a message to be logged by the LogMessage activity when the flow receives the input from the request that the trigger received and passed on to the flow.

   

   3. To configure the message, in the Functions section, expand string. Click concat(str, str2) to add the function to the message box. As the box is populated, the error message is cleared.

   

   4. Select str in the box and replace it by entering "Request received for: " (include the quotes too):
      string.concat(Request received for: ", str2)
4. Replace str2 with the last name of the passenger who booked the flight.
   (The last name of the passenger is passed on from the trigger to the flow. We had mapped this trigger output to flow input previously. Hence it is now available for mapping under $flow in Upstream Output.)
   1. Select str2.
   2. In the Upstream Output section, expand $flow.
   3. Click lastname.
   4. Click Save.

   

5. Close the LogMessage dialog box. The LogMessage activity is added to the right of the Flow Inputs & Outputs tab.

Your flow should now look like this:

Step 7: Add the first branch to check if the passenger’s last name is Jones

Tip: To watch this step in the video tutorial, click

To add a branch and configure its condition to look for the last name “Jones”:

1. Hover over the LogMessage activity and click .

   

   The branch is added and the Add Activity dialog box opens.

   

2. Close the Add Activity dialog box and configure the condition of the branch first. You must configure the branch with a condition to read the last name of the passenger.
3. Hover over to the end of the branch until you see a button with three dots placed horizontally.



4. Click the button to expose the following options and click .




5. In the Branch Mapping Settings dialog box opens, select the Success with condition branch condition.

   1. In the left pane, click condition to open the mapper in the right pane.
   2. In the right pane, configure the branch condition with a regular expression as follows:
      1. In the Functions section, expand the string category under Functions and click contains(str1, str2). The selected function is added to the condition box at the top of the right pane.

      2. Configure str1 in the expression to take the value of the last name that the user enters: In the Upstream Output, expand $flow > queryParams, and select lastname. This last name is the name entered by the user in the search query.

      3. Define str2 to be Jones: Replace str2 in the condition by manually typing Jones.
         
      4. Click Save. Now, this branch is configured to be executed when the name entered as a query parameter is Jones.

6. Add a Return activity to the branch in order to return the flight booking matching the last name Jones. To do so:

   1. Hover over the end of the branch and click .

   

   2. Scroll to the Default category and select it.
   
   3. Click Return to add the activity. The Return activity configuration window opens by default.
7. Configure the Return activity for the branch to output the flow results if this branch executes (when the passenger's last name is anything but Jones):
   1. Click code under Flow Outputs to open the mapper and type 200 in the code box, which is the HTTP success code.
   2. Expand the next flow output data. All the different elements under data that are returned by this activity are displayed. You must attribute a value to each field under data.
   3. Start by clicking Class under data and type "Business" as Jones is booked in Business Class.
   4. Click Cost to type a number of your choice. You can also use a function to randomize the value. To do so, in the Functions section, expand the number category and click random(). Enter 5000 as an input parameter to the random() function.
   5. Click DepartureDate to enter the departure date in any format of your choice. You must use quotation marks as the date needs to be specified as a string. For example, “01/01/21” or “January 1st, 2021” are valid values.
      
   6. Click DeparturePoint to enter the departure airport name of your choice. You must use quotation marks as the departure point needs to be specified as a string. For example, “LAX” or “LHR” are valid values.
   7. Click Destination to enter a string for this field. For example, “Paris” or “JFK” are valid values.
   8. Click FirstName to enter the first name associated with the last name Jones. For example, “Brian” or “Paul” are valid values.
   9. Click Id to enter a number of your choice. You can also use a function to randomize the value. To do so, in the Functions section, expand the number category and click random(). Enter 999999 as an input parameter to the random() function.
   10. Click LastName to map this field to the query parameter lastname. Before doing so, we can use a string function to capitalize the last name that is returned by our app. To do so, under Functions, expand string and click toTitleCase(str). Once string.toTitleCase(str) is added to your box, select str to replace it with the query parameter. Expand $flow and then queryParams under Upstream Output and click lastname. The box should look like this:
   11. Click Save and then close the dialog box.

   Your flow should look like this:

Step 8: Add a second branch to process any other passengers

Tip: To watch this step in the video tutorial, click

The second branch you add from the LogMessage activity executes when the success condition of the first branch is not matched. If the passenger's last name is not "Jones", the passenger's seat is in Economy Class.

To add a second branch from the LogMessage activity:

1. Hover your mouse cursor over the LogMessage activity and click .

   

   The branch gets added and the Add Activity dialog box opens.

2. Close the Add Activity dialog box.

3. Hover your mouse cursor to the end of the branch until you see a button with three dots placed horizontally. Click the button to expose the following options:

   

4. Click . The Branch Mapping Settings dialog box opens.
5. Select the Success with no matching condition branch condition. If the conditions of all the other Success with condition branches are not true, this branch is executed. This means, if the last name entered as a query parameter is not Jones, this second branch is executed.



6. Instead of manually adding another Return activity and enter the value of each field under data again, duplicate the Return activity from the first branch by hovering over the activity that you want to copy and click . The copied activity should appear next to your original Return activity:

   

7. Drag the duplicate activity to your second branch.
8. Click CopyOfReturn activity to configure the response this branch returns.
9. In the Flow Inputs section, expand data , select Class and type “Economy” as this branch should return Economy Class bookings.



10. Click Save and close the dialog box.
    Your flow should look like this:
    

Step 9: Validate the app

Tip: To watch steps 9 and 10 in the video tutorial, click

Your app is now ready. Before you push the app to the Cloud, validate all the flows to confirm that there are no errors or warnings. To do so, click Validate. Flogo Enterprise validates each flow and activity within the flow. If there are any errors or warnings, you see the respective icons next to the flow name or activity tab which contains the error or warning.

On a successful validation, you get the following message:

Step 10: Build the App

Your app is now ready to be built. There are two ways to build a Flogo app.

• As an executable file
• Build it as a Docker image in a Docker container

1. Click the left arrow next to the flow name to open the FlightApp page.

   

2. Click Build.
3. Select your target platform from the Build drop-down list. Select Windows/amd64 on Windows, Darwin/amd64 on Macintosh or Linux/amd64 or Linux/86 on Linux from the list.

   

   You see a Build log with the progress of the build command. When the build completes, you see an executable file called FlightApp-darwin_<processor> in your /Downloads directory.

Docker Image

1. Click Docker Image from the drop-down list. You should see a progress bar.
2. While the Docker image is being created, you see a Build log with the progress of the build command.
3. Once the image is created successfully, it is available in your local Docker repository. To view it in your Docker repository, open a terminal and run the following command:

   docker images

   You should see the docker image for your app:

   

   Note: Even though the app name contains camelCase, the name is converted to all lowercase letters when the Docker image is named. For example, "FlightApp" translates to "flightapp".

Step 11: Test the app

Now that the app has been built successfully, you run the app. Once it runs successfully, you can test your API in a REST client.

On Macintosh and Linux Platforms

To test the app:

1. Open a terminal and change directory to the location of FlightApp-darwin_amd64, FlightApp-linux_amd64 or FlightApp-linux_86 file depending on your platform.
2. Run the following commands:

   chmod +x <FlightApp-darwin_amd64>

   ./FlightApp-darwin_amd64

   Note: In the commands, use the file name specific to your platform - FlightApp-linux_amd64 or FlightApp-linux_86 in the case of Linux.
3. Click Allow in the following dialog box:

   

   The following messages are displayed in the console:

   

4. Make a note of the port number 9999 and path /flightbookings in the logs.
5. You can test your API in a REST client such as Postman by entering the port number 9999, path /flightbookings and query parameter lastname. For example, http://localhost:9999/flightbookings?lastname=jones.



In the above example, note that since the query parameter sent has the last name as "Jones", the Class in the response has been automatically set to Business Class.

6. Go back to your terminal. You should see the logs you configured with the Log activity.

Docker Image

1. Open a terminal.
2. Run the following command:

   docker run -p 9999:9999 flogo/flightapp

   You should see the following:



3. Test your API in a REST client such as Postman.
4. Press Ctrl + C to stop the docker container. Run docker ps -a to ensure that your container has stopped.