Creating Your First REST API

Step 1: Create an app

To create a Flogo app:

Procedure
1. Click Apps.
2. Click Create/Import. The What do you want to build? dialog opens.
3. To create a Flogo app: 
   • Under Quickstart > All app types;Apps, click Create a Flogo app.
   • In the block that displays below your selection, click Create Flogo app.

   A Flogo app is created with the default name in the New_Flogo_App_<sequential_app_number> format.

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

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

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

Note: Ensure that 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 that opens, click Schema to add a 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

Every app must have at least one flow and, in most cases, a trigger that initiates the flow. Create a 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:

Procedure
1. On the Flows page, click Create.

The Add triggers and flows dialog 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. On the FlightBookings flow page, click the Triggers icon. The trigger palette opens.
4. From the Triggers palette, drag the Receive HTTP Message trigger to the Triggers area on the left. The Configure trigger: ReceiveHTTPMessage dialog opens.
   
   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 and select the FlightResponse schema you defined earlier.

   The selected schema is automatically displayed in the Response Schema box.

   4. Click Continue.
5. Next, select Copy Schema when prompted.

   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 must look similar to the following image:

   
6. Lastly, close the Flow Inputs & Outputs tab.

Step 4: Map trigger output to flow input

When REST trigger receives a request from a passenger (a REST request), the data from the request is produced 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:

Procedure
1. Click the REST Trigger icon to open its configuration dialog.

In the Configuration dialog, 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 query parameter.

4. In the new row in the Query Parameters table, enter the value of ParameterName as lastname and click Save in the same row (in the Actions 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 Available data and Flow inputs panes are displayed. Flow inputs is the list of flow inputs that can be mapped to the trigger outputs in the Available data pane. Only headers are displayed in the flow inputs. The new query parameter is not visible yet.
   

6. Save the trigger configuration and click Sync to display the new values. Now, queryParams must open in the Flow inputs column.
   

7. In the Flow inputs column, click headers.

   The headers text editor on the right of Flow inputs is initially empty.

   

8. To 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. Drag headers from the Available data pane to headers in the Flow inputs pane. Alternatively, click headers from the Flow inputs pane, drag headers from the Available data pane into the text editor.
      The text editor must now display $trigger.headers and a connection line between the two panes. This indicates that you have successfully mapped the trigger output headers to the flow input header. The numbers at the end of the connection line indicate the total number of mappings for the selected element.
      
9. To map the flow input, in the Flow inputs column, click queryParams. The data mapper view is the same as the one while mapping headers. The queryParams text editor is initially empty. Drag queryParams from the Available data pane and drop it on queryParams in the Flow inputs pane. The text editor must now display $trigger.queryParams. This indicates that you have successfully mapped the trigger output queryParams to the flow input queryParams.
   

10. To save your progress, click Save.

    This completes the mapping of flow inputs.

Step 5: Map the flow output to trigger reply

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:

Procedure
1. In the left pane, click the Map from Flow Outputs tab to configure the mapping of the trigger reply. The Available data and Trigger reply panes are displayed. You can map the following trigger replies to the flow outputs - code and data.
   

2. In the Map from Flow Outputs section: 

   1. The Available data pane displays the data available for the mapping. $flow is displayed in this pane. To see all the flow outputs available for the mapping, expand $flow. This displays code and data.
   2. Drag code from Available data and drop it on code in the Trigger reply pane. $flow.code is displayed in the code text editor. You have successfully mapped the code in Trigger reply to the code in Available data.
      
   3. Repeat the same steps to map data from Trigger reply with data from Available data.
      
      
   Note: You can expand data in both the Trigger reply pane and the Available data pane to see the tree structure of the data you have defined in the schema.
3. Click Save and close the trigger dialog.
   

Step 6: Add a Log Message Activity to the flow

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:

Procedure
1. On the FlightBookings flow page, click Activities, the activities palette opens.
2. In the Activities palette, under General tab, select Log Message and drag it to the activities area.
   
3. Drag a connection line from StartActivity to the LogMessage activity that you have created.
4. Now, to configure the LogMessage activity with a message to log when it receives an incoming request from the ReceiveHTTPMessage trigger:
   1. Click the LogMessage activity to open the configurations dialog.
   2. Click the Input tab. The Available data and Activity inputs columns are displayed on the right side of the LogMessage activity tabs.
   3. Click the message to open the mapper to the right. Configure a message to be logged by the LogMessage activity when the input from the request that the trigger received is passed on to and received by the flow.
   4. To configure the message, click Functions, and expand the string. Click concat(str, str2) to add the function to the message box.
      
   5. Select str in the box and replace it by entering "Request received for: " (include the quotes too): string.concat(Request received for: ", str2).
5. Replace str2 with the family name of the passenger who booked the flight.
   (The family 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 Available data.)
   1. In the Available data pane, expand $flow and expand queryParams.
   2. Drag lastname and drop it in place of str2.
   3. Click Save.
   
6. Close the LogMessage dialog.

   Your flow must now look like this:

   

Step 7: Add the first Return Activity branch

To add a Return activity and the branch to configure its condition to look for the family name "Jones":

Procedure
1. From the Activities palette, drag Return activity available under Default category to the activity area.
2. Now, to configure a connection line between a LogMessage activity to the Return activity. Configure the branch with a condition to read the family name of the passenger.
3. Drag a highlighted arrow from the LogMessage activity to the Return activity.
4. Hover over and click the branch label on the connection line you just created. The configuration window for branch condition opens.

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

   1. ClickFunctions. Select the string>>contains(str1, str2). The selected function is added to the condition text editor.
   2. Configure str1 in the expression to take the value of the family name that the user enters. In the Available data, expand $flow > queryParams. Drag lastname to str1. This family name is the name entered by the user in the search query.
   3. Replace str2 in the condition by manually typing "Jones".
      
   4. Click Save. This branch runs when the name entered as a query parameter is Jones.
6. Now, Configure the Return activity for the branch to produce the flow results if this branch runs (when the passenger's family name is anything but Jones):
   1. Click the return activity to open the configuration dialog.
   2. Click code under Flow outputs to open the mapper and type 200 in the code box, which is the HTTP success code.
      
   3. Expand the next flow output data. All the different elements under data that are returned by this activity are displayed. Assign a value to each field under data.
   4. Start by clicking Class under data and type "Business" as Jones is traveling by "Business" class.
   5. 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.
   6. Click DepartureDate to enter the departure date in any format of your choice. Use quotation marks as the date needs to be specified as a string. For example, “01/01/21” or "January 1, 2021" are valid values.
      
   7. Click DeparturePoint to enter the departure airport name of your choice. Use quotation marks as the departure point needs to be specified as a string. For example, “LAX” or “LHR” are valid values.
   8. Click Destination to enter a string for this field. For example, "Paris" or “JFK” are valid values.
   9. Click FirstName to enter the first name associated with the family name Jones. For example, "Brian" or "Paul" are valid values.
   10. 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.
   11. Click LastName to map this field to the query parameter lastname. Before doing so, we can use a string function to capitalize the family name that is returned by our app. To do so, under Functions, expand the 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 Available data. Drag lastname and drop it in place of str. The text editor must look like this:
       
   12. Click Save and then close the Return Activity Configuration dialog.

       Your flow must look like this:

       

Step 8: Add a second Return Activity branch

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

To add a second branch from the LogMessage activity:

Procedure
1. Duplicate the Return activity from the first branch instead of manually adding another Return activity. You can copy the activity by clicking . The copied activity is displayed next to your original Return activity:
2. Click the CopyOfReturn activity to configure the response this branch return.
3. First, to create a connection between the LogMessage activity and the Return1 activity, hover over to the LogMessage activity, you see that an arrow highlighted. Drag the arrow to the Return activity.
4. 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 run. This means, if the family name entered as a query parameter is not Jones, this second branch is run.
   
5. Now, in the configuration window click the name of the activity to make it editable and rename the activity.
   
6. In the Flow outputs section, expand data, select Class, and type "Economy” as this branch must return "Economy" class bookings.
7. Click Save and close the dialog.

   Your flow must look like this:

   

Step 9: Validate the app

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

On successful validation, you get the following message:

Step 10: Push the app

Your app is now ready to be pushed. To push your app:

Procedure
1. Click the back arrow on the top-left corner or click the Apps tab to open the app details page.
   
2. Click Push.

   You see a message as Deploying while the app is being deployed.

3. After the app has finished deploying, you see the following status:
   

The app is in a stopped state since there are no instances of the app running. To run the app, hover over 0 to display the up and down arrows above and below 0 . Click the up arrow above 0 such that the 0 turns to 1, and click Scale. You see the Running status once the instance starts.

Step 11: Test the app in APITester

Now that the app has been pushed successfully, you can test the app using the APITester.

To test the app:

Procedure
1. Click Endpoints and then click Test.
   

   The API for the service you just created opens in the APITester.

2. Expand the GET operation by clicking anywhere on the flow name box.
   
3. Click Try it out.
4. Enter Doe for lastname value.
   
5. Click Execute in the blue bar.
6. The Response box displays the REST response. Since the family name in the request is not Jones, the passenger is automatically shown in "Economy" class as follows:
   

   Next, run the APITester with LastName set to Jones and ensure that the Class is set to "Business" class.

7. Click Clear as shown below:
   
8. Type "Jones" for lastname value.
   Note: The string for the family name is case-sensitive. So, "Jones" is viewed as different from "Jones".
   
9. Click Execute in the blue bar. The Response body box displays the REST response. Since the family name in the request is Jones, the passenger is automatically placed in "Business" class as shown below:
   
10. Click the Logs link to view the logs for the app.

    The request that the ReceiveToHTTPMessage trigger logged is displayed.