Topic: Using HTTPBuilder to make multipart HTTP POSTs to RESTful services
Date:  2014 SEP 24
We’ve been working on breaking up a large project into several smaller services linked through RESTful HTTP APIs. One such service transforms several source files and a few string parameters into binary output. This service accepts input as RFC2388 multipart form data. As part of the project, calls from a Grails-based frontend have to be submitted to this service, with the results being returned to the user’s browser.
The go-to library for making HTTP requests in Groovy is HTTPBuilder, a wrapper around Apache Commons HttpClient. It provides an API for building up HTTP requests without working directly with HttpClient, making for cleaner code that doesn’t look like someone pasted a bunch of Java into your Groovy service. Unfortunately, available examples seem to stop at trivial cases, bring in a lot of HttpClient usage, or rely on deprecated methods.
After reading through examples, HttpClient API documentation, and several other blog posts (this one being the most helpful), we now have a service that takes a few String parameters, a Map containing representations of the file components as key:value pairs, and returns a byte array after making a call to our RESTful backend service. Explanation below, code now:
Dependencies and Imports
For a freshly bootstrapped Grails application, you’re going to need to bring in a few extra dependencies to make this work. Here’s the dependency list with the versions that were current at the time of writing:
This gets your the minimum dependencies required to make the above service function. Note that newer versions of HttpClient deprecate classes like
MultipartEntity. Once you have the required dependencies brought into your project, the following imports will resolve:
Representing Our Inputs
The service we’re POSTing to takes a variable number of files and transforms them into a single binary output. Our Grails frontend is only one of a number of sources that use the REST API, but all API clients typically build up a Map representing the file components before building a multipart request. This Map uses the filenames as keys, with the file’s contents as an array of bytes as the value. For the frontend, these components can be processed as the result of a POST to the frontend, as shown below:
Representing the file components in this way allows for a single form input accepting a variable number of files. It also makes them easy to rip through, building parts for our multipart POST:
Handling the Results
Once the REST API has processed our files, the ID, and the version into a single binary file, it returns a 200 status code and the byte stream. HTTPBuilder handles this by calling a success closure. Providing a closure with an arity of two will result in the response and data stream being bound to the first and second arguments, respectively. The data argument arrives as an InputStream which must be read into a byte array:
Not too difficult!