This is a guest blog entry by David Dossot, co-author of the soon-to-be-released book Mule in Action.
I recently had the opportunity to integrate a bunch of REST resources and came to further appreciate what I consider to be Mule’s power tools: scripting and expressions (there is a third tool in my power box, Spring, but I won’t discuss it here).
Scripting, and more precisely Groovy, has been key to this REST integration for:
- Generating the desired request microformats
- Processing the HTTP responses
The particular integration I will discuss here, with details changed to protected the innocent, is a classic resource creation via HTTP POST:
- A client posts a new order as an XML entity that complies to a particular microformat
- If successful, the server responds 201 (created) with a Location header referring to the new resource URI
I realized this integration with the following Mule artifacts:
- A single synchronous HTTP outbound endpoint
- An inbound Groovy transformer for generating the posted entity
- Two response transformers for extracting useful information
Note that no HTTP concerns perspire beyond the boundaries of this endpoint. The incoming message is a map containing the details of the order, and the response message has:
- A boolean property indicating the outcome of the creation (thus simplifying further routing)
- The order ID as its payload (or an empty string if the creation failed)
Why an HTTP Endpoint?
At this point you may be wondering:
- Why not use the REST service component instead of an endpoint? Though this component works perfectly well for GET methods (and it helped me a lot in my project), it forces the content type to application/x-www-form-urlencoded for POST requests, which was not accepted by the resource I was targeting.
- Why not use the Restlet client, as demonstrated in Mule’s RESTpack? That would have certainly been an option, but the benefits would have been pretty slim: yet more classpath cluttering while not getting a lot more than what an HTTP outbound endpoint can already do. Using a standard HTTP outbound endpoint also has the advantage of having its exceptions handled in a consistent manner with the rest of the configuration.
Take a look at the endpoint:
This unique endpoint takes care of all the required aspects of a REST resource creation. Moreover, thanks to its transformers, it shields the rest of the configuration from knowing about the details of this integration.
Groovy’s MarkupBuilder Goodness
The heavy lifting is really done by Groovy’s MarkupBuilder, which offers a natural way to produce XML entities compliant to our particular microformat:
Notice how the values from the map payload are used to populate the XML elements: some of the naming convention mismatches are resolved here (for example, clientId becomes customerId).
This transformer produces the following output:
And it is all what the REST service was expecting!
More Groovy Happiness
The transformers in charge of extracting data from the response are also using Groovy, but this time in expressions:
After these two transformations have been applied, any router or service handling the message down the line will only have to care about the ResourceCreated property and the payload.
Even More Power
For XML entity responses, the XPath extractor has proven handy. The following uses an XPath expression to extract the value of an attribute as the new message payload:
For more complex processing, Groovy’s XmlSlurper has also proven very effective.
To see the complete XML configuration file, click here. With all these power tools in hand, integrating REST resources will surely not make you restless. Enjoy!
