Description

The REST plugin enables the usage of HTTPBuilder on a Grails application.

Usage

The plugins will inject the following dynamic methods:

• withHttp(Map params, Closure stmts) - executes stmts using a @HTTPBuilder@
• withAsyncHttp(Map params, Closure stmts) - executes stmts using an @AsyncHTTPBuilder@
• withRest(Map params, Closure stmts) - executes stmts using a @RESTClient@

Examples

Taken from HttpBuilder's Simplified GET Request

withHttp(uri: "http://www.google.com") {
   def html = get(path : '/search', query : [q:'Groovy'])
   assert html.HEAD.size() == 1
   assert html.BODY.size() == 1
}

Notice that you can call HTTPBuilder's methods inside @stmts@, the current HTTPBuilder is set as the closure's delegate. The same holds true for the other dynamic methods.

AsyncHTTPBuilder

import static groovyx.net.http.ContentType.HTML
withAsyncHttp(poolSize : 4, uri : "http://hc.apache.org", contentType : HTML) {
   def result = get(path:'/') { resp, html ->
      println ' got async response!'
      return html
   }
   assert result instanceof java.util.concurrent.Future
   while (! result.done) {
      println 'waiting...'
      Thread.sleep(2000)
   }
   /* The Future instance contains whatever is returned from the response 
      closure above; in this case the parsed HTML data: */
   def html = result.get()
   assert html instanceof groovy.util.slurpersupport.GPathResult
}

All dynamic methods will create a new http client when invoked unless you define an id: attribute. When this attribute is supplied the client will be stored as a property on the instance's metaClass. You will be able to access it via regular property access or using the id: again.

The code bellow is not working since Twitter moved to OAuth. We are working on an update that uses HttpBuilder's OAuth Support, stay tuned

class FooController {
  def loginAction = {
    withRest(id: "twitter", uri: "http://twitter.com/statuses/") {
      auth.basic model.username, model.password
    }
  }
  def queryAction = {
    withRest(id: "twitter") {
       def response = get(path: "followers.json")
       // …
    }
    /* alternatively
      def response twitter.get(path: "followers.json")
    */
  }
}

Configuration

Dynamic method injection

grails.rest.injectInto = ["Controller", "Service", "Routes"]

Proxy settings

You can apply proxy settings by calling @setProxy(String host, int port, String scheme)@on the client/builders at any time. You can also take advantage of the proxy: shortcut

withHttp(uri: "http://google.com", proxy: [host: "myproxy.acme.com", port: 8080, scheme: "http"])

This shortcut has the following defaults

• port: = 80
• scheme: = http

SSL Key-Store and Trust-Store support

If you are connecting to a server through HTTPS you might need to add a Key and or a Trust Store to the underlying SSL Socket Factory. Some examples are…

• The service you are connecting to requires some sort of SSL Cert authentication,
• You want to make sure that the server you are connecting to provides a specific certificate.
• You do not mind that the certificate that the server provides doesn't match the Domain Name that the server has.

Note, this last option will normally apply to development and test environments.

So how can I add the Key and/or Trust Stores to the underlying SSL Socket Factory?

The client will try to add a Key and a Trust Store if the URL of the host starts with `https`. By default it will attempt to locate a Key Store through the File System's path <User's Home>/.keystore e.g /home/berngp/.keystore and a Trust Store through the JVM Classpath @./truststore.jks@, you can override this by specifying a rest.https.keystore.path and/or rest.https.truststore.path configuration entries in the Config.groovy file.

Also by default it will try to open the stores using the following passwords '', 'changeit', 'changeme' but you can set a specific password through the rest.https.keystore.pass and rest.https.truststore.pass configuration entries. If for some reason it is unable to setup the underlying SSL Socket Factory it will fail silently unless the rest.https.sslSocketFactory.enforce configuration entry is set to `true`.

Specifying a Hostname Verification strategy for the Trust Store.

You can set three different Hostname Verification strategies through the rest.https.cert.hostnameVerifier configuration entry.

• ALLOW_ALL: The URL requested doesn't need to match the URL in the Certificate.
• STRICT: The URL requested needs to match the URL in the Certificate.
• BROWSER_COMPATIBLE: The URL requested must be in the same domain as the one in the Certificate. It accepts wildcards.

Example of a specific setup

/** SSL truststore configuration key */
rest.https.truststore.path = 'resources/certs/truststore.jks'
/** SSL keystore configuration key */
rest.https.keystore.path='resources/certs/keystore.jks'
/** SSL keystore password configuration key */
rest.https.keystore.pass='changeme'
/** Certificate Hostname Verifier configuration key */
rest.https.cert.hostnameVerifier = 'BROWSER_COMPATIBLE'
/** Enforce SSL Socket Factory */
rest.https.sslSocketFactory.enforce = true

Generating a Key Store

• Official JDK Guide
• Importing a Private Key into a KeyStore (JDK 1.6 and above)
• KeyMan - An non JDK Key Tool by IBM

Note: SSL The Key Store and Trust Store support is a new addition for the 0.6 release.