A common approach is to use the URI to version APIs (although this approach is discouraged in favour of Hypermedia). For example, you can define the following URL mappings:

That will match the following controllers:

This approach has the disadvantage of requiring two different URI namespaces for your API.

As an alternative Grails supports the passing of an Accept-Version header from clients. For example you can define the following URL mappings:

Then in the client simply pass which version you need using the Accept-Version header:

Another approach to versioning is to use Mime Type definitions to declare the version of your custom media types (see the section on "Hypermedia as the Engine of Application State" for more information about Hypermedia concepts). For example, in application.groovy you can declare a custom Mime Type for your resource that includes a version parameter (the 'v' parameter):

Or the equivalent in application.yml:

Then override the renderer (see the section on "Customizing Response Rendering" for more information on custom renderers) to send back the custom Mime Type in grails-app/conf/spring/resourses.groovy:

Then update the list of acceptable response formats in your controller:

Then using the Accept header you can specify which version you need using the Mime Type:

The RestfulController class contains code which does data binding for actions like save and update. The class defines a getObjectToBind() method which returns a value which will be used as the source for data binding. For example, the update action does something like this…​

By default the getObjectToBind() method returns the request object. When the request object is used as the binding source, if the request has a body then the body will be parsed and its contents will be used to do the data binding, otherwise the request parameters will be used to do the data binding. Subclasses of RestfulController may override the getObjectToBind() method and return anything that is a valid binding source, including a Map or a DataBindingSource. For most use cases binding the request is appropriate but the getObjectToBind() method allows for changing that behavior where desired.

You can also customize the behaviour of the controller that backs the Resource annotation.

The class must provide a constructor that takes a domain class as its argument. The second constructor is required for supporting Resource annotation with readOnly=true.

This is a template that can be used for subclassed RestfulController classes used in Resource annotations:

You can specify the super class of the controller that backs the Resource annotation with the superClass attribute.

For example, to implement the index action, simply call the respond method passing the list of objects to respond with:

Note that in the above example we also use the model argument of the respond method to supply the total count. This is only required if you plan to support pagination via some user interface.

The respond method will, using Content Negotiation, attempt to reply with the most appropriate response given the content type requested by the client (via the ACCEPT header or file extension).

If the content type is established to be HTML then a model will be produced such that the action above would be the equivalent of writing:

By providing an index.gsp file you can render an appropriate view for the given model. If the content type is something other than HTML then the respond method will attempt to lookup an appropriate grails.rest.render.Renderer instance that is capable of rendering the passed object. This is done by inspecting the grails.rest.render.RendererRegistry.

By default there are already renderers configured for JSON and XML, to find out how to register a custom renderer see the section on "Customizing Response Rendering".

The show action, which is used to display and individual resource by id, can be implemented in one line of Groovy code (excluding the method signature):

By specifying the domain instance as a parameter to the action Grails will automatically attempt to lookup the domain instance using the id parameter of the request. If the domain instance doesn’t exist, then null will be passed into the action. The respond method will return a 404 error if null is passed otherwise once again it will attempt to render an appropriate response. If the format is HTML then an appropriate model will produced. The following action is functionally equivalent to the above action:

The save action creates new resource representations. To start off, simply define an action that accepts a resource as the first argument and mark it as Transactional with the grails.gorm.transactions.Transactional transform:

Then the first thing to do is check whether the resource has any validation errors and if so respond with the errors:

In the case of HTML the 'create' view will be rendered again so the user can correct the invalid input. In the case of other formats (JSON, XML etc.), the errors object itself will be rendered in the appropriate format and a status code of 422 (UNPROCESSABLE_ENTITY) returned.

If there are no errors then the resource can be saved and an appropriate response sent:

In the case of HTML a redirect is issued to the originating resource and for other formats a status code of 201 (CREATED) is returned.

The update action updates an existing resource representation and is largely similar to the save action. First define the method signature:

If the resource exists then Grails will load the resource, otherwise null is passed. In the case of null, you should return a 404:

Then once again check for errors validation errors and if so respond with the errors:

In the case of HTML the 'edit' view will be rendered again so the user can correct the invalid input. In the case of other formats (JSON, XML etc.) the errors object itself will be rendered in the appropriate format and a status code of 422 (UNPROCESSABLE_ENTITY) returned.

If there are no errors then the resource can be saved and an appropriate response sent:

In the case of HTML a redirect is issued to the originating resource and for other formats a status code of 200 (OK) is returned.

The delete action deletes an existing resource. The implementation is largely similar to the update action, except the delete() method is called instead:

Notice that for an HTML response a redirect is issued back to the index action, whilst for other content types a response code 204 (NO_CONTENT) is returned.

The HttpClient interface forms the basis for the low-level API. This interfaces declares methods to help ease executing HTTP requests and receive responses.

The majority of the methods in the HttpClient interface returns Reactive Streams Publisher instances, and a sub-interface called RxHttpClient is included that provides a variation of the HttpClient interface that returns RxJava Flowable types. When using HttpClient in a blocking flow, you may wish to call toBlocking() to return an instance of BlockingHttpClient.

There are a few ways by which you can obtain a reference to a HttpClient. The most simple way is using the create method

Consult the Http Client section of the Micronaut user guide for more information on using the HttpClient low-level API.

A declarative HTTP client can be written by adding the @Client annotation to any interface or abstract class. Using Micronaut’s AOP support (see the Micronaut user guide section on Introduction Advice), the abstract or interface methods will be implemented for you at compilation time as HTTP calls. Declarative clients can return data-bound POGOs (or POJOs) without requiring special handling from the calling code.

Note that HTTP client methods are annotated with the appropriate HTTP method, such as @Get or @Post.

To use a client like the one in the above example, simply inject an instance of the client into any bean using the @Autowired annotation.

For more details on writing and using declarative clients, consult the Http Client section of the Micronaut user guide.

Spring Framework 7 can create an HTTP client from an interface annotated with @HttpExchange and @GetExchange. This is a Spring API, not a Grails DSL or a controller contract.

For a synchronous client, create a proxy with RestClient:

Spring 7 can also register the proxy as a bean. Group related interfaces and configure their shared RestClient builder:

The registered BookClient can then be constructor-injected into an application bean and called like any other interface. Synchronous methods can return a decoded body, HttpHeaders, or ResponseEntity.

For Mono or Flux return values, add Spring WebFlux to the classpath and use WebClient instead. Register the group with clientType = ClientType.WEB_CLIENT and configure it through WebClientHttpServiceGroupConfigurer; reactive applications also need Reactor types on the classpath.

HTTP interface parameters cannot be null unless the parameter is optional. By default, 4xx and 5xx responses raise an exception. Configure status handling on the underlying RestClient or WebClient when an API requires different behavior.

That is all the build-time command needs. To serve the description at runtime as well, add springdoc, and optionally Swagger UI:

The command starts the application context, without a web server, and writes the default document to build/openapi/openapi.yaml and each group to build/openapi/openapi-<group>.yaml. A character of the group’s name a file name cannot hold, such as the / of admin/v1, is written as -, so that group is written to openapi-admin-v1.yaml; where two groups would then be written to one file, the command writes nothing and names them. The --output-directory and --format options, or the grails.openapi.output-directory and grails.openapi.output-format settings, choose where and whether YAML or JSON is written:

Because the command starts the application, it needs whatever the application needs to start in the environment it runs in, such as a datasource.

Where springdoc is configured, the command applies the method filters, operation customizers and OpenAPI customizers springdoc applies to the documents it serves, so each file describes what springdoc serves. That holds only in an environment where springdoc is enabled: with springdoc.api-docs.enabled: false, as an application generated with the openapi feature has in production, springdoc configures nothing, so the command writes no springdoc.group-configs group and applies none of springdoc’s filters and customizers, and says so; grails.openapi.groups are written as ever. A filter or customizer that fails there, such as one that reads the current request, is skipped and logged, rather than the operations it was applied to.

To package the description and serve it as a static file, include it in the application’s static resources when the application is assembled:

It is then served at /static/api/openapi.yaml, and any viewer can render it. For example, Redoc needs only a page that points at the file:

With springdoc on the classpath no further configuration is required. springdoc registers its own resource handlers, so Swagger UI is served even though Grails leaves Spring Boot’s catch-all resource handler disabled, and the springdoc paths fall through the Grails URL mappings because they resolve to no controller.

The Grails operations are added to each document before any other springdoc customizer runs, so an OpenApiCustomizer bean, a GlobalOpenApiCustomizer bean, or a customizer a GroupedOpenApi adds sees them and can change them. springdoc runs an OpenApiLocaleCustomizer before all of those, though, so one does not see the Grails operations, and the generate-open-api command, which answers no request in a locale, does not run one.

springdoc describes the application’s own Spring MVC endpoints as it does without Grails, since Jackson rather than Grails renders what they return: a domain class one of them returns is described with everything Jackson writes of it, such as a getter with nothing persisted behind it, and with the whole of what it is associated with. Where a Grails endpoint in the same document uses the class too, it is described once, as Grails renders it, and the Spring MVC endpoint refers to that schema as well. A class springdoc describes under the same name as another the Grails endpoints use is named apart from it, as below, in each document on its own.

An application whose URL mappings include a catch-all that resolves to a view or a controller - a single page application forwarding unmatched paths to an index view, or an API answering unmatched paths with a 404 of its own - needs nothing more either: the paths springdoc serves are excluded from the URL mappings, at springdoc.api-docs.path and springdoc.swagger-ui.path where they are configured, while springdoc serves them.

Where springdoc is used, its own springdoc.paths-to-match, springdoc.paths-to-exclude, springdoc.packages-to-scan, springdoc.packages-to-exclude, springdoc.produces-to-match, springdoc.consumes-to-match and springdoc.headers-to-match apply to the Grails endpoints of the default document too, and springdoc.api-docs.version chooses between OpenAPI 3.1, the default, and 3.0 for both the build-time and the runtime description.

By default every action a URL mapping reaches is described. An application whose published API is only part of what it serves can narrow that down:

The media type settings select the way springdoc selects a Spring MVC handler method: an operation is described only where it produces, or consumes, exactly the media types a setting lists. An operation produces the media types of its controller’s responseFormats, application/json where it declares none, and consumes the same media types where it binds a body. A mapping declared for a version declares the Accept-Version header it is matched on, so headers-to-match: Accept-Version=1.0 selects the operations of version 1.0. Any other header criterion leaves every Grails endpoint out, as it leaves out a Spring handler method that declares no header condition:

Where springdoc is used, its method filters decide for the Grails actions too. Each filter is called with the method the action is declared as, and an action a filter excludes is left out, at runtime and by the generate-open-api command. An OpenApiMethodFilter bean applies to the default document, a GlobalOpenApiMethodFilter bean to every document, and a filter a GroupedOpenApi adds to that group:

The create and edit actions of a RestfulController answer the forms an HTML client renders, so they are left out unless grails.openapi.include-form-actions is set.

A group is a document of its own, describing part of the application for one audience:

Each group takes the same paths-to-match, paths-to-exclude, packages-to-scan, packages-to-exclude, produces-to-match, consumes-to-match and headers-to-match settings as the default document, and display-name titles it. The generate-open-api command writes each group to a file of its own, and at runtime springdoc serves each at /v3/api-docs/<name>, applying the same criteria to any Spring MVC endpoints the application also has. A group declared to springdoc, in springdoc.group-configs or as a GroupedOpenApi bean, is honored the same way, both at runtime and by the command. Where springdoc is used, its own top-level criteria, such as springdoc.paths-to-match, apply to every group ahead of the group’s own, criterion by criterion, as springdoc applies them to its Spring MVC endpoints. A group name declared more than once is described by its first declaration, and logged, since springdoc may select the group’s Spring MVC endpoints by another:

What describes the API as a whole - its title and description, its servers, how it is secured, the descriptions of its tags, vendor extensions for a viewer, and endpoints the application does not map itself, such as a login endpoint a security plugin provides - is written once, in a base document the description starts from:

The information, servers, security and external documentation of the base document are used as they are. Its tags, extensions and components are kept beside what is derived, and so are its paths, in each document whose path settings select them. Where the base document declares no version, the application’s info.app.version is used, and without a base document the description is titled with info.app.name.

Every URL mapping that names a controller statically becomes a path. A resources mapping contributes each of its generated HTTP methods:

produces GET and POST on /books, and GET, PUT, PATCH and DELETE on /books/{id}, with POST, which Grails maps to update as well, where the controller’s allowedMethods allows it.

A RestfulController constructed read only answers 405 from its write actions, so only what it serves is described:

mapped with "/publishers"(resources: 'publisher'), produces only GET on /publishers and /publishers/{id}. A write action the controller overrides is described, because it does whatever the override does.

URL variables become OpenAPI path parameters, so "/books/$id" is documented as /books/{id}. The optional .format extension Grails appends to REST mappings is omitted, because OpenAPI describes response formats through content types rather than the path. An OpenAPI path parameter is always required, so a mapping with an optional variable, such as "/photos/$id?", is documented at both /photos/{id} and /photos. A mapping with a wildcard that captures nothing, such as a catch-all "/**", cannot be written as an OpenAPI path and is not documented.

A mapping that names a controller but no action is documented as the controller’s default action. One that takes the action from the path, such as "/topics/$action"(controller: 'topic'), is documented for each action the controller declares, and, where the action is optional, as "/topics/$action?" makes it, at the path without it as the controller’s default action. One that chooses the action by the method of the request, such as action: [GET: 'show', DELETE: 'delete'], is documented for each method. A mapping whose action is decided by a closure as each request is made is skipped, and logged.

A mapping declared for an HTTP method is documented for that method, unless the controller’s allowedMethods refuses it for the action, which Grails answers with 405. A mapping that accepts any method is documented for the methods allowedMethods declares for the action, or, where it declares none, for the method a RestfulController action of that name answers, and GET for any other action. A mapping that names a namespace is documented with that namespace’s controller, so versioned controllers of the same name are each described at their own routes.

A mapping declared for a version is matched on the Accept-Version header a request sends:

A request asking for no version is answered by the highest version, so that is the one the default document describes, with an optional Accept-Version parameter naming it. Grails also takes the version from a v parameter of the Accept media type, which is not described. A group describes another version by selecting its header, and there the parameter is required:

A RestfulController is described as serving the type it declares: BookController extends RestfulController<Book> responds with, and accepts, a Book, whatever the controller is named. The type may be a domain class or any other class, such as a command object the controller renders in place of the domain class. A controller that is not a RestfulController declares no response type, so its responses are described without a body unless an annotation declares one.

A type is described in components/schemas through swagger-core, so a @Schema or Jackson annotation on the class or on one of its properties is honored. The metaClass every Groovy object has and the errors a validateable object has are not part of it.

A property of a class the Grails operations are described with - a domain class, a command object, or any other class, such as one an @ApiResponse names - is described by the name Grails' converters, JSON views and data binding render and bind it by: its own. So neither a @JsonProperty rename, which Grails ignores, nor the name Jackson would otherwise write, such as isbn for ISBN, changes it, and a command object’s request parameters are described by the names Grails binds them by. Where the description should name a property otherwise, @Schema(name) renames it, and its constraints, and whether it is required or read only, follow the rename. A class only springdoc’s own Spring MVC endpoints use keeps the names Jackson writes, since Jackson renders it there.

A schema is named after its class, or after the name a @Schema annotation on the class declares. Classes sharing a name in different packages are each named by their package as well, such as com.example.v1.Book and com.example.v2.Book, so neither stands in for the other and the names do not depend on which is described first. A class sharing the name of a schema the base document declares, or one the document derives, such as ValidationErrors or a Patch schema, is named by its package in the same way. Only a class described as a schema of its own takes a name: an enum is described where it is used unless @Schema(enumAsRef = true) describes it as a schema of its own, and a class described in the place of another - the implementation a @Schema annotation names, or the value a @JsonValue accessor returns - leaves the name to the class described.

The declared constraints of a domain class or a Validateable class are applied over that result, because swagger-core cannot see them. The two combine, so the annotation above supplies the prose and the constraints block the validation:

The constraints are carried across as follows:

Where the annotation and the constraints both say whether a property must be sent, the property’s @Schema wins: a property it declares nullable = true or requiredMode = NOT_REQUIRED is not listed in required, and one it declares requiredMode = REQUIRED is, whatever it is constrained to. So a Validateable class that declares no constraints, whose every property Grails constrains nullable: false by default, still describes the properties it annotates as optional that way.

A domain class is described as Grails renders it: its identifier and its persistent properties. A transient, or a getter with nothing persisted behind it, is not rendered and is not described. The version is not rendered either unless it is configured to be, and is described only then: in JSON with grails.converters.json.domain.include.version, or grails.converters.domain.include.version for every format. The document describes the version where JSON renders it, so a version rendered in XML alone, with grails.converters.xml.domain.include.version, is not described.

A property data binding does not bind is marked readOnly: the identifier and the version, which the server assigns, dateCreated and lastUpdated, a property constrained bindable: false, and a property a command object can only read. Tools that understand OpenAPI leave a read-only property out of a request body, so one schema describes both directions.

A property described by a reference to another schema, such as an embedded class, keeps what is said of it, being nullable, whether its constraint or its @Schema says so, or read only, or the description, deprecation or access mode @Schema gives it. OpenAPI 3.1 says so beside the $ref, and a nullable one is oneOf the reference and a null type. OpenAPI 3.0 ignores anything beside a $ref, so there the property is allOf the reference, and says it on that.

An association to another domain class is described by the associated identifier, which is what Grails renders for it and what it binds it from:

A to-many association is an array of those references, and an embedded association is described in full.

A class that cannot be introspected is left out of the document and logged, rather than failing the document, and an operation that referred to it is described without a shape rather than with a reference that does not resolve. A class whose constraints cannot be evaluated is described without them, and logged.

An operation that accepts a body describes the type the action binds. Where the action takes a command object that is the command, in preference to the resource the controller serves:

Where one of the actions RestfulController declares takes no command object, the body is the resource the controller serves, whether the controller inherits the action or overrides it. Any other action binds a body only where it takes a command object or declares one. A patch binds only what it is sent, so its body is a copy of the resource’s schema, named for it with a Patch suffix, that requires nothing. A body with a property a file is bound to, a MultipartFile or a Part, is described as multipart/form-data, with the file as a binary string. An action that binds something else declares it with @RequestBody, which replaces what is derived.

The actions RestfulController declares are described by the part each plays in the resource, so the statuses are the ones it answers with rather than a uniform 200. That holds for an action the controller overrides as much as for one it inherits: an override is how an action is annotated, and it still lists, shows, creates, updates or deletes the resource:

Any other action of the controller, such as a search, is described as any controller’s action is: a 200, a 404 where its path has a variable, and whatever its annotations declare.

A 422 answers with the validation errors Grails renders for a request that cannot be bound, described once as the ValidationErrors schema, or as grails.validation.ValidationErrors, after the class Grails renders them from, where the document already describes something else as ValidationErrors, such as a class of the application a Spring MVC endpoint returns. The converters render them, in JSON as an object listing them and in XML as an errors element holding an error element for each. Where a JSON view renders them, as the errors view of an application generated with JSON views does, they are described in JSON as that view renders them: one error with its message, path and link, or several embedded with their total. The status is the one the view sets, which is 422 for the errors view an application is generated with. So:

A response and a request body are described in the media types of the formats the controller declares in responseFormats, for the action or for every action, and in application/json where it declares none. A format is described as the first media type the application configures for it in grails.mime.types:

describes each body as application/json and as text/xml, the first media type Grails configures for xml by default. Only a data format, json or xml, carries the shape described; a format that renders a view, a form or a HAL document, such as html or hal, is listed without one. A request body is described in the data formats alone.

The XML is described as the converters render it, with the OpenAPI xml object: a domain class or a command object as an element named for its class, such as book, its identifier as the id attribute and its version as an attribute, an association as an element carrying the associated identifier as the id attribute, a collection of values as an element holding one named for the class of each, such as <lines><string>a</string></lines>, and a listing as a list element holding one for each. The xml object cannot describe a map, which Grails renders as entry elements keyed by an attribute, and the document describes the XML Grails renders by default, not that of grails.converters.xml.default.deep or grails.converters.xml.domain.include.class.

RestfulController answers its own save and update with a Location header naming the resource, which the 201 and 200 responses describe, and its patch too, which update serves. The header is something only RestfulController’s code sends, rather than part of what the action answers by its role, since a controller generated for a REST application does not send it. So an action the controller overrides is described without it, and one that sends it declares it with `@ApiResponse(headers).

A listing accepts the paging and sorting RestfulController passes to GORM, so those are described on it:

An index the controller overrides is described with them too. One that does not page withdraws them, as it would any parameter derived for it:

The identifier an operation of a RestfulController addresses is described with the type the domain class declares for it:

An association to the domain class is described with the same type. A @Parameter declared for the identifier refines it, and keeps that type unless its schema names another.

An action parameter of a simple type is bound from the request by name, so it is described as a query parameter of that type:

This needs the parameter names, which Grails keeps by default through the preserveParameterNames setting of the Grails Gradle plugin. A parameter renamed with @RequestParameter is described by the name a request sends. A parameter an action reads from params rather than declaring is described with @Parameter. A parameter Grails does not bind - one declared as Object, an interface or an abstract class - is not described.

A command object an action binds on a request without a body, such as a GET, is bound from the request parameters, so each property it binds that a request parameter can carry is described as a query parameter, with its constraints:

A path variable is described with the type of what it is bound to: the identifier of the resource an operation addresses, the identifier of the resource a nested mapping names it by, such as bookId in /books/{bookId}/chapters, or else the action parameter of the same name. A pattern or a list of values the mapping constrains it to is described too:

What is derived can be corrected or enriched with the standard OpenAPI annotations. They are read by swagger-core, so they mean what they mean on any other endpoint:

An action answers success with the statuses it declares, so a success status declared on the action, or in its @Operation, replaces any other success status derived for it, with what that said, such as a Location header. A save that queues what it is sent, rather than creating it, and declares @ApiResponse(responseCode = '200', description = 'Queued') is described answering 200, not 201. An error status an action declares is added to those derived, and a status its controller declares is added to each of its actions, and kept beside the success status an action declares.

Where springdoc is used, its operation customizers are given each Grails operation too, once the annotations are applied, with a HandlerMethod of the controller and the method the action is declared as: an OperationCustomizer bean for the default document, a GlobalOperationCustomizer bean for every document, and a customizer a GroupedOpenApi adds for that group. A customizer that returns null leaves the operation out. A schema a customizer adds to the components is kept under the name it gives it, and is not named apart from the classes the Grails operations are described with. The generate-open-api command applies them the same way:

A REST application maps its controllers without naming them, either by naming the action and leaving the controller to the request, as a generated REST API does:

or by leaving both, as the default mapping does:

Either way the REST controllers those mappings reach are described, at the URLs the mapping serves: RestfulController subclasses, and controllers declaring the formats they respond in with responseFormats, none of them html. The first form above produces GET /book, POST /book and GET /book/{id}; the second produces GET /book/index, POST /book/save and GET /book/show/{id}, and, because its action is optional, GET /book for the controller’s default action. An application whose mappings name every controller gets neither, because expansion follows the mappings rather than the controllers.

A mapping that captures the namespace, such as "/$namespace/$controller/$action?/$id?", reaches each controller at its own namespace, and does not reach a controller without one. A mapping that leaves the namespace out reaches the controller Grails resolves for the name alone, so of two controllers sharing a name only a namespaced mapping reaches either.

A controller a resources mapping names and a mapping that does not name it are described at both, because both answer. Where that gives two operations the same identifier the second is qualified by the path it is reached at, so no two operations in the document share one. An application wanting only the first form removes the default mapping from its UrlMappings.

A controller rendering views for a browser declares no responseFormats, or declares html among them, such as a login controller responding in html and json, so it does not appear in the document. Where responseFormats is a map by action, each action is decided by its own entry: with [index: ['json'], page: ['html', 'json']], index is described and page, like an action the map leaves out, is not. responseFormats is read as respond reads it, a list, or a list for each action; an array is not one, so respond answers in any configured format, html too. Controllers @Scaffold generates extend RestfulController, and those generate-controller generates for a REST application declare responseFormats, so both are described; those it generates for a web application render views and are not.

A controller that is not a RestfulController but whose save and update actions bind the same domain class, as the controllers generated for a REST application do, answers the actions RestfulController declares as a RestfulController of that class does, so they are described the same way: with its statuses, the domain class as its responses and bodies, and the paging of its listing. Its other actions are described as any controller’s are.

As mentioned previously, Grails maintains a registry of grails.rest.render.Renderer instances. There are some default configured renderers and the ability to register or override renderers for a given domain class or even for a collection of domain classes. To include a particular property from rendering you need to register a custom renderer by defining a bean in grails-app/conf/spring/resources.groovy:

To exclude a property, the excludes property of the XmlRenderer class can be used:

As mentioned previously, the default renders use the grails.converters package under the covers. In other words, under the covers they essentially do the following:

Why the separation between converters and renderers? Well a renderer has more flexibility to use whatever rendering technology you chose. When implementing a custom renderer you could use Jackson, Google Gson or any Java library to implement the renderer. Converters on the other hand are very much tied to Grails' own marshalling implementation.

The JSON converter renders date and time values the same way as Spring Boot’s default Jackson JsonMapper, so a Grails application and a Spring Boot application return the same JSON for the same values:

An OffsetTime keeps its seconds and writes a fraction of a second with only the digits it needs, as JSON views render it, where Spring Boot writes "03:00-03:00". A map keyed by Date, Calendar or ZonedDateTime values renders its keys as those values render by default, such as "2025-10-08T07:48:46.407Z", also where grails.converters.json.date or a registered marshaller changes how the values render; other map keys render with their toString(). JSON views render dates and times the same way.

A Month renders by its name, such as "SEPTEMBER", as every enum does, where Spring Boot writes its number. Data binding binds a Month from either.

Setting grails.converters.json.date to javascript renders java.util.Date values as JavaScript new Date(…​) constructors instead. To render a type differently, register an object marshaller for it, for example in BootStrap.init. This one renders a Month as its number, as Spring Boot does:

A grails.rest.render.ContainerRenderer is a renderer that renders responses for containers of objects (lists, maps, collections etc.). The interface is largely the same as the Renderer interface except for the addition of the getComponentType() method, which should return the "contained" type. For example:

To return HAL instead of regular JSON for a resource you can simply override the renderer in grails-app/conf/spring/resources.groovy with an instance of grails.rest.render.hal.HalJsonRenderer (or HalXmlRenderer for the XML variation):

You will also need to update the acceptable response formats for the resource so that the HAL format is included. Not doing so will result in a 406 - Not Acceptable response being returned from the server.

This can be done by setting the formats attribute of the Resource transformation:

Or by updating the responseFormats in the controller:

With the bean in place requesting the HAL content type will return HAL:

To use HAL XML format simply change the renderer:

To return HAL instead of regular JSON for a list of resources you can simply override the renderer in grails-app/conf/spring/resources.groovy with an instance of grails.rest.render.hal.HalJsonCollectionRenderer:

With the bean in place requesting the HAL content type will return HAL:

Notice that the key associated with the list of Book objects in the rendered JSON is book which is derived from the type of objects in the collection, namely Book. In order to customize the value of this key assign a value to the collectionName property on the HalJsonCollectionRenderer bean as shown below:

With that in place the rendered HAL will look like the following:

If you wish to use a custom Mime Type then you first need to declare the Mime Types in grails-app/conf/application.groovy:

Or the equivalent in grails-app/conf/application.yml:

Then override the renderer to return HAL using the custom Mime Types:

In the above example the first bean defines a HAL renderer for a single book instance that returns a Mime Type of application/vnd.books.org.book+json. The second bean defines the Mime Type used to render a collection of books (in this case application/vnd.books.org.booklist+json).

With this in place issuing a request for the new Mime Type returns the necessary HAL:

An important aspect of HATEOAS is the usage of links that describe the transitions the client can use to interact with the REST API. By default the HalJsonRenderer will automatically create links for you for associations and to the resource itself (using the "self" relationship).

However you can customize link rendering using the link method that is added to all domain classes annotated with grails.rest.Resource or any class annotated with grails.rest.Linkable. For example, the show action can be modified as follows to provide a new link in the resulting output:

Which will result in output such as:

The link method can be passed named arguments that match the properties of the grails.rest.Link class.