Sometimes we want to support in our RESTful API a different level of detail in the output for the same resource. For example a default output with the basic fields and a more detailed output with all fields for a resource. The client of our API can then choose if the default or detailed output is needed. One of the ways to implement this in Grails is using converter named configurations.
Grails converters, like
XML, support named configurations. First we need to register a named configuration with the converter. Then we can invoke the
use method of the converter with the name of the configuration and a closure with statements to generate output. The code in the closure is executed in the context of the named configuration.
The default renderers in Grails, for example
DefaultJsonRenderer, have a property
namedConfiguration. The renderer will use the named configuration if the property is set to render the output in the context of the configured named configuration. Let’s configure the appropriate renderers and register named configurations to support the named configuration in the default renderers.
In Grails we can apply the
@Resource AST (Abstract Syntax Tree) annotation to a domain class. Grails will generate a complete new controller which by default extends
grails.rest.RestfulController. We can use our own controller class that will be extended by the
@Resource transformation. For example we might want to disable the
delete action, but still want to use the
@Resource transformation. We simply write a new
RestfulController implementation and use the
superClass attribute for the annotation to assign our custom controller as the value.
We can write a RESTful application with Grails and define our API in different ways. One of them is to subclass the
RestfulController already contains a lot of useful methods to work with resources. For example all CRUD methods (
save/show/update/delete) are available and are mapped to the correct HTTP verbs using a URL mapping with the
Especially when we use Grails to create a RESTful API we want to enable the request header
Accept, so Grails can do content negotiation based on the value in the header. For example we could use the request header
Accept: application/json to get a JSON response. Grails will look at the
boolean configuration property
grails.mime.use.accept.header to see if the
Accept header must be parsed. The default value is
true so the
Accept header is used. But there is another property which determines if the
Accept header is used:
grails.mime.disable.accept.header.userAgents. The value must contain a list or a regular expression pattern of user agents which are ignored for the
Accept header. The default value is
~/(Gecko(?i)|WebKit(?i)|Presto(?i)|Trident(?i))/. So for any request from these user agents, mostly our web browser, the
Accept header is ignored.