The Art Of Building REST Services in TIBCO Cloud Integation

You shouldn’t have to be a Swagger expert to get started with designing and building your new API. Creating an API from scratch can be a difficult task, so what if you could create API without writing a line of code?

The newly introduced Web Integrator in TIBCO Cloud Integration believes in being an API-led platform that can make it as easy as possible for people to get started building REST services. Simply think about the message you want to receive and the response you want to send back is all you need to create your API.

Let’s build

For now we’ll create a FlightBookings app, that sends an email confirmation to the user requesting air travel.

Create the app

As with every type of app you want to deploy to TIBCO Cloud Integration, you need to create an app first using the orange Create button. The newly introduced Web Integrator is powered by TIBCO’s OSS Project Flogo and the mascot (Flynn) is in the interface as well. Click on the Create a Web Integrator App to get started.

Create the flow

Click the orange button Create a flow to create a new flow and select Rest Trigger to move to the next screen. On this page is where you configure your API. The resource path is path your API will listen on. As a best practice the resource is the plural form of a noun so books or apps, or as in our case, flightbookings. The methods you select are the HTTP methods that clients can use to invoke your API. The HTTP methods supported by Web Integrator are:

• GET: Get the resource specified (e.g. get a single book or get all books)
• POST: Create a new resource of the object (e.g. create a new flightbooking)
• PUT: Update a resource or create a new one if it doesn’t exist yet (e.g. update an app or create a new one)
• DELETE: Remove the resource (e.g. delete the cookie)

The app we’re building should create new flightbookings in the system so the method to choose would be POST. Because creating a JSON schema can actually be quite difficult, the Web Integrator gives you the ability to paste in a sample message that can be used as input and output (we can change that later). The input message should contain the details that are important to the API to do its job. You can copy/paste the message from here to the input box on the screen. When you’re done, click on Create

{  
"Class": "string",  
"DepartureDate": "2017-05-27",  
"Destination": "string",  
"FirstName": "string",
"EmailAddress": "string"
}

Obviously you can have more fields, but I think this is good for now

Implement logic

Now that we’ve got the creation out of the way, let’s focus on the business logic. After you click on the newly created flow you’ll be greeted by a canvas with two tiles. One is called ReceiveHTTPMessage and will trigger the start of the flow and the other is ReplyToHTTPMessage which sends a message back to the client invoking the API. To implement the logic we’ll do three things:

1. Add a log tile to log that a new message is received
2. Add an email tile to send an email from our flow
3. Update the ReplyToHTTPMessage to send back the data we need

Adding a log tile

The first thing we want to do is log that a new message has been received. Click on the ReplyToHTTPMessage and drag it two spaces over so that there are two spaces available to add new tiles.

Click on the first empty tile and select the Log Message tile. Your new tile is automatically selected and it does need an input. On the Input click on message to start crafting the message we want to log. There are a whole bunch of functions available that can help creating something unique, but in this case we’ll go for a simple function to concatenate two string.

On the right hand side of the screen you can configure the message by typing in the textbox or by clicking on the parameters and functions you want to use. In this case a viable alternative is to copy the statement from below :)

string.concat("A new booking request has arrived for ", $TriggerData.body.FirstName)

This function concatenates a string with the FirstName passed in as a parameter

Sending an email

The second step is about sending an email. In one of my previous blogs I explained how you can send emails from Web Integrator, so I’ll skip that part. If you want to read up on it, you can go to this post. To configure the rest of the email activity it needs 4 inputs:

1. sender: who is the message coming from (e.g. some@email.com)
2. recipients: who is the email going to; this will be the email address that as passed in as a parameter. Click on the recipients item and you can use the search functionality to find the EmailAddress inside $TriggerData (or copy $TriggerData.body.EmailAddress)
3. subject: the subjectline of your email (e.g. thank you for requesting a flight)
4. message: the actual body of the email; in this will use the concat function again to concatenate the FirstName with a bit of predefined text:

string.concat("Dear ", string.concat($TriggerData.body.FirstName, ". Thank you for requesting a flight. Please note we'll take care of it soon!"))

Updating the ReplyToHTTPMessage

Rather than sending back the same message as we received we can actually update the Input Settings with a new sample of the response we want to use. As a response we want to reply with the FirstName we got from the input, a unique identifier to identify the request and the current date. The sample message you can paste in should look something like:

{  
"FirstName": "string",
"ID": "string",
"Date": "string"
}

As you paste that in, it automatically updates the fields that are available on the Input tab. If you go there, you’ll find there are three fields that need an input mapping:

1. FirstName: Which we can map directly from the TriggerData ($TriggerData.body.FirstName)
2. ID: A unique identifier can be a random number between 0 and 999999 (number.random(999999))
3. Date: Today’s date (datetime.currentDate())

Push your app

Now that everything is mapped and configured, we’re ready to go! Click the blue Push app button to turn the app on.

Test it

After pushing the app you’ll be directed back to the Apps page. From there you click on View and Test 1 Endpoint and click on View API to see the test page for your shiny new app. On the input of the POST method, the only required item is the body. That of course needs your input parameters:

{
"Class": "string",
"DepartureDate": "string",
"Destination": "string",
"EmailAddress": "string",
"FirstName": "string"
}

Be sure to replace the value of EmailAddress with an actual email address to make sure you see the result :)

In the Tester page the response body should be something like:

{
"Date": "2017-08-15+00:00",
"FirstName": "string",
"ID": 623436
}

Conclusion

With a few easy steps you can create your own API to request flight bookings to a tropical paradise! As always let me know your thoughts on this tutorial either by commenting below or posting something on the TIBCO Community!