2. Introduction to Grails 2.3 REST
The Concept of a “Resource”
• Map data to a URL Endpoint
• Traverse object graph through URL mappings
• Provide serialization in your favorite format
• Driven by the HTTP Request’s Accept header
• Limitations:
• The whole URL graph needs to be explicitly defined for
mapping nested Resources
3. Introduction to Grails 2.3 REST
Defining a Resource
•
•
•
•
Decorate your domain object with the @Resource Annotation
Map to a URI via Annotation or UrlMapping
Use built-in, good-for-most-things RestfulController, or…
Build a custom controller to handle your specific use-case
4. Introduction to Grails 2.3 REST
Customizing Resource Behavior
•
•
•
Regulate response formats through the @Resource annotation
Determine read/write behavior
• In turn, writable actions will get 405
Customizing response
5. Introduction to Grails 2.3 REST
Resource Renderers
•
•
Provides inherent support for versioning
Built-in Renderers like DefaultJsonRenderer, HalJsonRenderer
offer some standard support
• include/exclude properties
• Handling versioning
6. Introduction to Grails 2.3 REST
Resource Renderers
•
•
•
•
•
•
Custom Renderers satisfy specific needs
Intercept the response activity to influence the output
Allow for changing the response structure
This is the place to put business logic that responds with a nonstandard view
Preferred over JSON.registerObjectMarshaller
Auto-wireable Spring beans
7. Introduction to Grails 2.3 REST
Resource Controllers
From the JAX-RS Spec…
"Adopting the MVC terminology, JAX-RS resource classes are
comparable to controllers"
https://jcp.org/en/jsr/detail?id=339
• Grails maps a RestfulController to the Resource’s URL, so the
@Resource is not the handler, it just represents the handler!
8. Beyond the Basics
Custom RestfulController
•
•
•
•
Overload how resources are resolved
Custom binding logic
Interface with services for object composition
• Business Logic: “Only show me healthy applications”
Using the respond method
• Control the response format this way
10. Getting Practical
Obscuring Ids
•
•
•
Custom RestfulController
• Overload queryForResource, listAllResources
Custom Renderer
• Only expose the properties that you want people to see
The @RestIdProperty strategy for building HAL Navigation
11. Getting Practical
Resources as a Concept
•
Nothing hard-ties a Resource to a domain object
•
Can be backed simply by a command object
•
Good choice for providing data in a format that is domainspecific, but brought in via service call
12. Getting Practical
Using Hyper-Media Practically
•
Built-in Grails rendering constructs don’t favor reusability
•
grails-rest-renderers plugin can provide some simplifications to
building pragmatic hyper-media renderers
http://grails.org/plugins/grails-rest-renderers
13. Getting Practical
Security?
Great article about REST Security from Dave Syer (@david_syer):
http://blog.cloudfoundry.com/2012/10/09/securing-restful-webservices-with-oauth2/
Summary:
Oauth: "one of the key reasons for OAuth2 to exist is so that
Client applications do not need to collect user credentials. Here is
where the learning curve for OAuth2 gets steeper.”
Form Login: Difficult to drive RESTful interactions since failures
are redirected to login page
Basic Auth: Maybe the best choice
Editor's Notes
show default url-mappings-reportshow querying the graph
Show @Resource(formats = …)Show url-mappings-report with UrlMapping and w/ uri defined on Resource
> Demonstrate include/exclude properties on DefaultJsonRendererDemonstrate Application HalJsonRendererapplicationRenderer(JsonRenderer, Application, new MimeType("application/json", [v: "1.0"]))Our persistence model (ie our domain model) doesn’t always make sense as a View Model, so for that we need some finer-grained control
> Demonstrate include/exclude properties on DefaultJsonRenderer> Demonstrate Application HalJsonRendererOur persistence model (ie our domain objects) doesn’t always make sense as a View Model, so for that we need some finer-grained controlShow Android app view model consumer example.