When you send a request to an API and it gets processed the API might want to notify you app about the status of the request. In order for your application to handle this callback you would have to set up an endpoint to listen for the notification and then send the url of that endpoint to the API. For example Twilio, one of the most popular public APIs, uses callbacks to tell you whether a SMS message has been successfully delivered or not in addition to a SMS id that you can use later for tracking purposes. Since the goal of the new Mule DevKit is to make things simpler it provides an easy way to handle HTTP callbacks.
Handling HTTP callbacks with the Mule DevKit
The Mule DevKit provides a special data type to facilitate the scenario in which a Mule flow needs to be invoked when a HTTP callback is received. The org.mule.api.callback.HttpCallback interface exposes the method getUrl() which tells you the URL to use in order to invoke a particular flow when a callback is received:
The Message Processor that gets generated by the Mule DevKit can be consumed as follows:
where handleSuccessFlow and handleFailureFlow are two flows that don't have any inbound endpoints whatsoever:
A couple of things to notice:
- parameters of type HttpCallback are appended a "-flow-ref" suffix to emphasize the fact that you need to pass a flow name in the Mule configuration XML file.
- a method can take any number of HttpCallback parameters
- a parameter of type HttpCallback can be annotated with @Optional
Callbacks in the Twilio Cloud Connector
As I mentioned before, Twilio API uses callbacks to tell you about the status of your requests. Wether you are making an outbound callback or sending a SMS message, Twilio API allows you to send a URL where you'll receive information about the phone call once it ends or the status of the outbound SMS message after it's processed by Twilio. Let's consider the following two flows:
The first one simply uses the Twilio Cloud Connector to send a SMS message. The second one will get executed when Twilio notifies your app about the SMS message status. Notice that the flow 'callbackFlow' has no inbound endpoint but is referenced by the status-callback-flow-ref attribute in send-sms-message.
Conclusion
What I find interesting about this feature is that it not only simplifies the development of Cloud Connectors but users of the Cloud Connector get a nice and intuitive way of saying "hey, invoke this flow when X happens" without knowing too much about callbacks, inbound endpoints, URLs and all that detail.
More information on this new feature can be found here. Another good source of information is the Twilio Cloud Connector source code.
follow: @federecio @mulejockey
