(Quick Reference)

4 Resources

4.1 What Are Resources

Root resources are classes that contain RESTful API services as defined by the JSR-311 JAX-RS standard. Such classes contain methods that service an API endpoint. These classes and methods make extensive use of annotations to define their properties and behavior, such as the path in a URL, what content types endpoints consume and produce, and what HTTP methods each endpoint supports.

Oracle has an excellent article explaining how to create root resource classes and detail the annotations provided byJAX-RS.

4.2 Creating Resources

Any *Resource.groovy file created under grails-app/resources is assumed to be a JAX-RS resource and auto-detected by the jaxrs plugin. These resources are checked for the presence of JAX-RS annotations as defined by JAX-RS 1.1 specification, section 3.1. Resources that aren't properly annotated are ignored by the plugin.

When running applications locally, resource classes are watched and reloaded when any change to them occurs.

4.3 Generating Resources

As a convenience, the jaxrs plugin provides a script that will create a simple resource skeleton that can be built upon. The default template generates a simple root resource class with a single method implementing a GET API. The script can be called as follows:

In the above example, a new resource class will be generated at the path grails-app/resources/class/path/NameResource.groovy with an API root path of /api/name.

The default template can be overridden by applications by placing a new template in src/main/templates/artifacts/Resource.groovy. Use the default template as a reference on the variables used to build the resource class.

A more powerful script that will generate root resources for a domain class is documented in the Scaffolding Domains section.