7.6 Content Negotiation - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
Version: 3.0.11
7.6 Content Negotiation
Grails has built in support for Content negotiation using either the HTTPAccept
header, an explicit format request parameter or the extension of a mapped URI.Configuring Mime Types
Before you can start dealing with content negotiation you need to tell Grails what content types you wish to support. By default Grails comes configured with a number of different content types withingrails-app/conf/application.yml
using the grails.mime.types
setting:grails: mime: types: all: '*/*' atom: application/atom+xml css: text/css csv: text/csv form: application/x-www-form-urlencoded html: - text/html - application/xhtml+xml js: text/javascript json: - application/json - text/json multipartForm: multipart/form-data rss: application/rss+xml text: text/plain hal: - application/hal+json - application/hal+xml xml: - text/xml - application/xml
grails-app/conf/application.groovy
as shown below:grails.mime.types = [ // the first one is the default format
all: '*/*', // 'all' maps to '*' or the first available format in withFormat
atom: 'application/atom+xml',
css: 'text/css',
csv: 'text/csv',
form: 'application/x-www-form-urlencoded',
html: ['text/html','application/xhtml+xml'],
js: 'text/javascript',
json: ['application/json', 'text/json'],
multipartForm: 'multipart/form-data',
rss: 'application/rss+xml',
text: 'text/plain',
hal: ['application/hal+json','application/hal+xml'],
xml: ['text/xml', 'application/xml']
]
Content Negotiation using the format Request Parameter
Let's say a controller action can return a resource in a variety of formats: HTML, XML, and JSON. What format will the client get? The easiest and most reliable way for the client to control this is through aformat
URL parameter.So if you, as a browser or some other client, want a resource as XML, you can use a URL like this:http://my.domain.org/books?format=xml
format
property on the response
object with the value xml
.You can also define this parameter in the URL Mappings definition:"/book/list"(controller:"book", action:"list") { format = "xml" }
withFormat()
method:import grails.converters.JSON import grails.converters.XMLclass BookController { def list() { def books = Book.list() withFormat { html bookList: books json { render books as JSON } xml { render books as XML } '*' { render books as JSON } } } }
withFormat()
that matches the requested content type. So if the preferred format is html
then Grails will execute the html()
call only. Each 'block' can either be a map model for the corresponding view (as we are doing for 'html' in the above example) or a closure. The closure can contain any standard action code, for example it can return a model or render content directly.When no format matches explicitly, a
(wildcard) block can be used to handle all other formats.There is a special format, "all", that is handled differently from the explicit formats. If "all" is specified (normally this happens through the Accept header - see below), then the first block of withFormat()
is executed when there isn't a
(wildcard) block available.You should not add an explicit "all" block. In this example, a format of "all" will trigger the html
handler (html
is the first block and there is no *
block).
withFormat { html bookList: books json { render books as JSON } xml { render books as XML } }
When using withFormat make sure it is the last call in your controller action as the return value of the withFormat
method is used by the action to dictate what happens next.
Using the Accept header
Every incoming HTTP request has a special Accept header that defines what media types (or mime types) a client can "accept". In older browsers this is typically:*/*
text/xml, application/xml, application/xhtml+xml, text/html;q=0.9, text/plain;q=0.8, image/png, */*;q=0.5
application/json
grails.mime.disable.accept.header.userAgents
, which is configured to detect the major rendering engines and ignore their ACCEPT headers. This allows Grails' content negotiation to continue to work for non-browser clients:grails.mime.disable.accept.header.userAgents = ['Gecko', 'WebKit', 'Presto', 'Trident']
format
to json
as you'd expect. And of course this works with the withFormat()
method in just the same way as when the format
URL parameter is set (although the URL parameter takes precedence).An accept header of '*/*' results in a value of all
for the format
property.If the accept header is used but contains no registered content types, Grails will assume a broken browser is making the request and will set the HTML format - note that this is different from how the other content negotiation modes work as those would activate the "all" format!
Request format vs. Response format
As of Grails 2.0, there is a separate notion of the request format and the response format. The request format is dictated by theCONTENT_TYPE
header and is typically used to detect if the incoming request can be parsed into XML or JSON, whilst the response format uses the file extension, format parameter or ACCEPT header to attempt to deliver an appropriate response to the client.The withFormat available on controllers deals specifically with the response format. If you wish to add logic that deals with the request format then you can do so using a separate withFormat
method available on the request:request.withFormat { xml { // read XML } json { // read JSON } }
Content Negotiation with URI Extensions
Grails also supports content negotiation using URI extensions. For example given the following URI:/book/list.xml
"/$controller/$action?/$id?(.$format)?"{
format
variable in the path. If you do not wish to use content negotiation via the file extension then simply remove this part of the URL mapping:"/$controller/$action?/$id?"{
Testing Content Negotiation
To test content negotiation in a unit or integration test (see the section on Testing) you can either manipulate the incoming request headers:void testJavascriptOutput() { def controller = new TestController() controller.request.addHeader "Accept", "text/javascript, text/html, application/xml, text/xml, */*" controller.testAction() assertEquals "alert('hello')", controller.response.contentAsString }
void testJavascriptOutput() { def controller = new TestController() controller.params.format = 'js' controller.testAction() assertEquals "alert('hello')", controller.response.contentAsString }