Consuming and developing and testing web services with Groovy and Grails

For a recent project that I did for Trifork (formerly known as JTeam), I used Groovy and Grails to both consume and provide and test webservices. In this post I would like to share a few of the highlights, and the rationale behind some of the choices I made. What I hope that you will get out of this, is that using Groovy and Grails for building web services is a very attractive option.

My task was to develop a system that acted as an intermediary between other systems, communicating using SOAP and REST. I developed both a SOAP and a REST service endpoint, as part of a Grails project. To test my system, I created unit and functional tests using Spock and Gradle. It was not clear from the beginning that I was going to use these tools, so I’d like to tell you how I ended up choosing them. So in short, these are the artefacts that I ended up with:

  • A Grails project that provided the REST and SOAP services to the system’s clients, and with all unit and integration tests for my code.
  • A Gradle-built project containing all functional tests.
Often, people associate Grails with doing quick mockups of CRUD screens for an application. I have found it to be a very good tool to use to go to production with a wide variety of webbased apps, even this project, which did not even have a GUI. In this project, all my code was written in Groovy, I didn’t need to fall back to Java for anything.
Note: I used Grails 1.3.7, as of writing of this article, version 2.x is out, but 2.x was not available at the time. Not too much has changed though.

REST Service

This was fairly easy to do, thanks to the REST support built into Grails. The key to getting started here is in section 13.1 of the Grails Userguide, by adding a line to conf/UrlMappings.groovy you can map specific HTTP methods to controller method names.

"/product/$id?"(resource:"product")

So I just created a controller, and used Spock to write unit tests for it. This way it was easy to get full branch coverage, and never looked back.

To output JSON was as simple as something like this:

// a Product object has been fetched previously
render(contentType: "text/json") {
  id = product.id
  name = product.name
}

Also, you can register a Converter in conf/Bootstrap.groovy but is just a little bit more involved, in the sense that it requires a developer to be aware that there is such a thing as globally registering a converter per class. So I applied the principle of least astonishment and left it at the above. So for the ‘show’ method, which returns a JSON representation of a Product object, I created two Spock unit tests: one that checks that the expected JSON come back, and another that checks that a 404 is returned when the required Product object does not exist. That leaves you with something like this:

class ProductControllerSpec extends ControllerSpec {
  def existingProduct
  def id = 1

  def setup(){
    existingProduct = new Product(id:id, name: 'my product')
    mockDomain(Product, [existingProduct]) //mocks database interaction
  }

  def 'retrieve the existing Product'(){
    given:
      controller.params.id = id
    when:
      controller.show()
    then:
      mockResponse.status == 200
  }

  def 'attempt to retrieve a non-existing Product'(){
    given:
      controller.params.id = 'foobar'
    when:
      controller.show()
    then:
      mockResponse.status == 404
  }
}

I know, there is nothing really exciting going on here. But the point is to show how little code it takes to do the regular stuff that you will have to get right (and keep it that way) in your project anyway. This is what Grails is all about: making the regular stuff easy so you can devote your time to the most complicated parts of your app.

Soap Service

This was a bit more tricky. I had several options here: the Grails Spring Webservices plugin was the first option I checked out. It only supported using Spring-WS 1.5 (and not 2.x). To start a new project using an outdated version of any library doesn’t seem like a good idea so I looked for alternatives. I ended up simply using plain Spring-WS, but developing my Soap endpoint code in Groovy (in the src/groovy directory). This was a major win, I could just create a Groovy MySoapEndpoint class, annotate it with Spring WS’s @Endpoint annotation and off I went.

Handling XML has always been a pain, even if a lot progress has been made by framework developers. With Groovy it is very easy to parse and produce XML, using XMLSlurper and XML MarkupBuilder, respectively. So, there is no marshalling or unmarshalling going on. There’s many libraries in Java that can do (un)marshalling, but they distract you from your end goal: parse and produce XML. These two tools have saved me a huge number of LOC compared to a Java-based solution.

Functional Tests

I created a Groovy project using Gradle (50 lines of Groovy, try doing that with Maven) with a bunch of Spock tests. Under the hood I used Commons HttpClient and avoided Groovy HttpBuilder because I find its API confusing. I am not the only one having trouble with it. Furthermore I needed to fiddle with SSL client certificates and I could only find out how to do that with HttpClient. The functional tests completed my delivery cycle which looked like this:

  1. Run Unit and Integration tests using ‘grails test-app’ locally.
  2. Commit and let Jenkins run all tests
  3. Let a Jenkins trigger fire the functional tests on the T environment of my DTAP street.

With all of the above passing and having 96% branch coverage, I could be confident about the quality of a release and haven’t experienced any cases of regression. Mind you, that’s not because I’m such a superstar-coder, it’s only because all these Groovy tools made things so darn easy.

Conclusion

I hope this article has given you an overview of what’s on offer for you once you choose Groovy to do develop/consume web services. For me it has been a good experience, and I hope it can be similar for you.

, , ,

6 Responses to Consuming and developing and testing web services with Groovy and Grails

  1. Sean Gilligan October 24, 2012 at 2:22 am #

    Any chance you could share a sample of your Groovy/Spock/HttpClient test code? It would be nice to be able to see what Groovy/Spock code looks like using HttpClient.

  2. Sean Gilligan October 24, 2012 at 2:47 am #

    By-the-way, I found this example which is pretty close:
    http://roshandawrani.wordpress.com/2011/02/12/grails-functional-testing-a-file-upload-using-httpbuilder-spock/

  3. Hans Westerbeek November 7, 2012 at 10:09 pm #

    Sean,

    Sorry for the late reply.

    I didn’t use HttpBuilder. I found its interface a bit too confusing, and in my case the main problem to solve was dealing with SSL client certificates. So I just wrapped the normal java HttpClient inside a class that represented what my the webservice client was able to do.

    That client, in turn, was used as a utility a bunch of Spock specs that performed the functional tests. Remember, it was not my webservice client that was under test, it was the webservice itself.

  4. Clara Wood July 31, 2013 at 10:01 am #

    In grails now also include REST technology for more flexibility.

    is not really a technology in itself, but more an architectural pattern. REST is very simple and just involves using plain XML or JSON as a communication medium, combined with URL patterns that are “representational” of the underlying system, and HTTP methods such as GET, PUT, POST and DELETE.

Trackbacks/Pingbacks

  1. Questa settimana in Grails (2012-12) - luca-canducci.com - Il blog di Luca Canducci: notizie, tips e nuove tecnologie dal mondo dell’IT. - March 26, 2012

    [...] Consuming and developing and testing web services with Groovy and Grails [...]

  2. An Army of Solipsists » Blog Archive » This Week in Grails (2012-12) - March 26, 2012

    [...] Consuming and developing and testing web services with Groovy and Grails [...]

Leave a Reply