Restful Grails 3

The pdf converter shrinks the slides. If you want a better view go to https://jlstrater.github.io/restful-grails3

Transcript

1. RESTFUL WEB SERVICES IN GRAILS 3 by Jenn Strater @jennstrater
2. Current  http://jlstrater.github.io/restful-grails3 Slides(source)
3. Previous Versions Gr8Conf EU  Source |Slides
4. ABOUT ME Professional Senior Consultant - Full Stack Engineer Co-Founder - Object Partners Gr8Ladies
5. ABOUT ME Minneapolis, MN Connect on Social Media @jennstrater https://linkedin.com/in/jennstrater https://github.com/jlstrater Twitter LinkedIn Github
6. AGENDA Remedial REST Ways To Improve A RESTful API with Grails Examples Related Grails Plugins
7. WHAT THIS TALK WILL NOT COVER Scalability of Grails APIs Security Ingesting RESTful APIs
8. REMEDIAL REST
9. TERMINOLOGY Application Programming Interface (API) Web Service Representational State Transfer (REST)
10. DEFINITION REpresentational State Transfer (REST) is an architectural style that describes how distributed data objects, or resources, can be defined and addressed, stressing the easy exchange of information and scalability.(Fischer 2013.)
11. HISTORY Described in Roy Fielding's 2000 PhD dissertation Fielding, Roy. . 2000. Architectural Styles and the Design of Network-based Software Architectures
12. GOALS To create a uniform interface between components Decouple implementations from the underlying services
13. CHARACTERISTICS
14. UNIFORM INTERFACE Individual Resources are identified using URIs Resources are abstracted from the data source and can be manipulated before being sent to a client Hypermedia As The Engine Of Application State (HATEOAS)
15. STATELESS Self-contained and independent requests Improves scalability Allows for parallel processing of requests Lets resources be viewed in isolation
16. CLIENT-SERVER Decoupled clients and servers Increases portability Easier to scale
17. LAYERED SYSTEM Endpoints can be the terminus or an intermediary service Allows for load balancing and intermediate security enforcers
18. WHY CHOOSE REST? Easy to implement Usable across many different platforms and languages
19. WHY REST AND GRAILS? Many helpful defaults Other advantages of Grails Ease of development Shorter development time
20. QUESTIONS ABOUT REST?
21. WAYS TO IMPROVE A RESTFUL API (WITH GRAILS)
22. SCOPE De-coupled server and client NO GSPs!
23. NEW IN GRAILS 3 Based on Spring Boot Switched to Gradle for build system Major structural changes Configuration Scripts
24. GETTING STARTED Resource Transformation i m p o r t g r a i l s . r e s t . R e s o u r c e @ R e s o u r c e ( u r i = ' / g r 8 l a d i e s ' ) c l a s s G r 8 L a d y { S t r i n g f i r s t S t r i n g l a s t }
25. GETTING STARTED URL mappings Or --> /gr8ladies/{id}/chapter U R L m a p p i n g s . g r o o v y " / g r 8 l a d i e s " ( r e s o u r c e s : " g r 8 l a d y " ) " / g r 8 l a d i e s " ( r e s o u r c e s : " g r 8 l a d y " ) { " / c h a p t e r " ( c o n t r o l l e r : " c h a p t e r " , m e t h o d : " G E T " ) }
26. HTTP STATUS CODES 200 is ok ... but not for everything
27. HTTP STATUS CODES Learn the correct status codes for different errors Code Description 2XX Successful 200 OK 4XX Client Error 400 Bad Request 403 Forbidden 404 Not Found 5XX Server Errors 500 Internal Server Error 502 Bad Gateway an exerpt fromhttp://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
28. HTTP STATUS CODES IN GRAILS Many of the cases are handled by Grails or the server(i.e. 5XXs) i f ( s o m e C o n d i t i o n ) { r e n d e r s t a t u s : 4 X X }
29. HTTP VERBS GET to retrieve a resource POST to create a new resource PUT to update an existing resource DELETE to remove an existing resource
30. HTTP VERBS IN GRAILS RESOURCE ANNOTATION Handled by Default! :)
31. HTTP VERBS IN GRAILS On each Controller c l a s s G r 8 L a d y C o n t r o l l e r { s t a t i c a l l o w e d M e t h o d s = [ l i s t : " G E T " , s a v e : " P O S T " , u p d a t e : " P U T " ] }
32. HTTP VERBS IN GRAILS URL Mappings " / g r 8 l a d i e s " ( r e s o u r c e : " g r 8 l a d y " , m e t h o d : " G E T " )
33. ENDPOINTS LIST h t t p : / / e x a m p l e . c o m / r e s o u r c e SHOW h t t p : / / e x a m p l e . c o m / r e s o u r c e / { i d }
34. ENDPOINTS h t t p : / / e x a m p l e . c o m / r e s o u r c e / { i d } NOT h t t p : / / e x a m p l e . c o m / r e s o u r c e ? i d = a b c 1 2 3 NOT h t t p : / / e x a m p l e . c o m / r e s o u r c e / { i d } / ? a c t i o n = d e l e t e NOT h t t p : / / e x a m p l e . c o m / r e s o u r c e / a d d
35. CONSISTENT STYLE CASING / r e s o u r c e s NOT / R e S o U r C e S
36. CONSISTENT URI STYLE Try Either: / m u l t i W o r d R e s o u r c e s Or: / m u l t i - w o r d - r e s o u r c e s And stick to it. Don't Mix and Match!
37. CONSISTENT STYLE RESOURCE NAMES plural nouns preferred h t t p : / / e x a m p l e . c o m / u s e r s vs h t t p : / / e x a m p l e . c o m / u s e r
38. SEARCH h t t p : / / e x a m p l e . c o m / r e s o u r c e ? f i e l d N a m e = v a l u e Lookup based on values
39. MULTIPLE MEDIA TYPES (JSON, XML) XML and JSON are most common
40. MULTIPLE MEDIA TYPES (JSON, XML) IN GRAILS XML by default By Parameter h t t p : / / e x a m p l e . c o m / r e s o u r c e . j s o n
41. MULTIPLE MEDIA TYPES (JSON, XML) IN GRAILS Available formats g r a i l s : m i m e : t y p e s : . . . j s o n : [ ' a p p l i c a t i o n / j s o n ' , ' t e x t / j s o n ' ] , . . . x m l : [ ' t e x t / x m l ' , ' a p p l i c a t i o n / x m l ' ]
42. MULTIPLE MEDIA TYPES (JSON, XML) IN GRAILS By Resource Requesting another type returns a 406 (Not Acceptable) i m p o r t g r a i l s . r e s t . R e s o u r c e @ R e s o u r c e ( u r i = ' / g r 8 l a d i e s ' , f o r m a t s = [ ' j s o n ' ] ) c l a s s G r 8 L a d y { . . . }
43. MULTIPLE MEDIA TYPES (JSON, XML) IN GRAILS By RestfulController Remember to add any response formats for versioned mime types c l a s s G r 8 L a d y C o n t r o l l e r e x t e n d s R e s t f u l C o n t r o l l e r { s t a t i c r e s p o n s e F o r m a t s = [ ' j s o n ' , ' x m l ' ] }
44. CUSTOM RESPONSE FORMATS Filter from default responses Provide different responses per version Provide response formats based on security
45. CUSTOM RESPONSE FORMATS IN GRAILS Object Marshallers g r a i l s - a p p / i n i t / B o o t s t r a p . g r o o v y Usage i m p o r t g r a i l s . c o n v e r t e r s . J S O N c l a s s B o o t s t r a p { d e f i n i t = { s e r v l e t C o n t e x t - > J S O N . r e g i s t e r O b j e c t M a r s h a l l e r ( G r 8 L a d y ) { d e f r e t u r n A r r a y = [ : ] r e t u r n A r r a y [ ' f i r s t N a m e ' ] = i t . f i r s t r e t u r n A r r a y [ ' l a s t N a m e ' ] = i t . l a s t r e t u r n A r r a y [ ' c h a p t e r ' ] = i t . c h a p t e r ? . n a m e r e t u r n r e t u r n A r r a y } } } r e n d e r g r 8 l a d y a s J S O N
46. CUSTOM RESPONSE FORMATS IN GRAILS Object Marshallers g r a i l s - a p p / c o n f / s p r i n g / r e s o u r c e s . g r o o v y i m p o r t g r a i l s . c o n v e r t e r s . J S O N i m p o r t o r g . g r 8 l a d i e s . C h a p t e r M a r s h a l l e r b e a n s = { J S O N . r e g i s t e r O b j e c t M a r s h a l l e r ( n e w C h a p t e r M a r s h a l l e r ( ) ) }
47. CUSTOM RESPONSE FORMATS IN GRAILS Object Marshallers c l a s s G r 8 L a d y M a r s h a l l e r i m p l e m e n t s O b j e c t M a r s h a l l e r < J S O N > { p u b l i c b o o l e a n s u p p o r t s ( O b j e c t o b j e c t ) { r e t u r n o b j e c t i n s t a n c e o f G r 8 L a d y } p u b l i c v o i d m a r s h a l O b j e c t ( O b j e c t o b j e c t , X M L c o n v e r t e r ) { G r 8 L a d y g r 8 l a d y = ( G r 8 L a d y ) o b j e c t c o n v e r t e r . c h a r s g r 8 l a d y . d i s p l a y N a m e } }
48. HYPERMEDIA AS THE ENGINE OF APPLICATION STATE (HATEOAS)* link to the resource and navigation { " _ l i n k s " : { " s e l f " : { " h r e f " : " / g r 8 l a d i e s " } , " n e x t " : [ { " h r e f " : " / g r 8 l a d i e s ? p a g e = 2 " } ] } }
49. HATEOAS IN GRAILS JSON Hypertext Application Language (HAL) g r a i l s - a p p / c o n f / s p r i n g / r e s o u r c e s . g r o o v y i m p o r t g r a i l s . r e s t . r e n d e r . h a l . * b e a n s = { h a l G r 8 L a d y R e n d e r e r ( H a l J s o n R e n d e r e r , o r g . g r 8 l a d i e s . G r 8 L a d y ) }
50. HATEOAS IN GRAILS Usage: Content Negotiation c u r l - i - H " A c c e p t : a p p l i c a t i o n / h a l + j s o n " h t t p : / / l o c a l h o s t : 8 0 8 0 / g r 8 l a d i e s / 1 H T T P / 1 . 1 2 0 0 O K S e r v e r : A p a c h e - C o y o t e / 1 . 1 C o n t e n t - T y p e : a p p l i c a t i o n / h a l + j s o n ; c h a r s e t = I S O - 8 8 5 9 - 1 { " _ l i n k s " : { " s e l f " : { " h r e f " : " h t t p : / / l o c a l h o s t : 8 0 8 0 / g r 8 l a d i e s / 1 " , " h r e f l a n g " : " e n " , " t y p e " : " a p p l i c a t i o n / h a l + j s o n " } } , " n a m e " : " " G r a c e H o p p e r " " }
51. PAGINATION* Parameters h t t p : / / e x a m p l e . c o m / r e s o u r c e ? o f f s e t = 0 & m a x = 1 0 d e f l i s t ( ) { L i s t g r 8 l a d i e s = G r 8 L a d y . l i s t ( m a x : p a r a m s . m a x , o f f s e t : p a r a m s . o f f s e t ) r e s p o n d [ r e s u l t s : g r 8 l a d i e s , m a x : p a r a m s . m a x , o f f s e t : p a r a m s . o f f s e t ] }
52. VERSIONING* URI h t t p : / / e x a m p l e . c o m / v 1 / r e s o u r c e / { i d } Custom Header Content Type G E T h t t p s : / / e x a m p l e . c o m / r e s o u r c e v e r s i o n : 2 . 0 G E T h t t p s : / / e x a m p l e . c o m / r e s o u r c e A c c e p t : a p p l i c a t i o n / v n d . e x a m p l e . v 2 + j s o n
53. VERSIONING IN GRAILS URI @ R e s o u r c e ( u r i = ' / g r 8 l a d i e s / v 1 ' ) @ R e s o u r c e ( u r i = ' / g r 8 l a d i e s / v 2 ' ) Accept Header " / g r 8 l a d i e s " ( v e r s i o n : ' 1 . 0 ' , r e s o u r c e s : " g r 8 l a d y " , n a m e s p a c e : ' v 1 ' ) " / g r 8 l a d i e s " ( v e r s i o n : ' 2 . 0 ' , r e s o u r c e s : " g r 8 l a d y " , n a m e s p a c e : ' v 2 ' )
54. READ-ONLY MODE for public APIs (or security)
55. READ-ONLY MODE IN GRAILS @ R e s o u r c e ( u r i = " / g r 8 l a d i e s " , r e a d O n l y = t r u e ) c l a s s G r 8 L a d y { S t r i n g f i r s t . . . }
56. RELATED PLUGINS FOR OTHER GRAILS VERSIONS
57. SPRING SECURITY REST PLUGIN Token based Authentication based on Spring-Security Last Updated May 2015 Source & Documentation
58. RESTFUL API PLUGIN Last Updated November 2014 Source & Documentation
59. REST RENDERER Last Updated February 2014 Source & Documentation
60. CONCLUSIONS REST is an architecture style, not a standard There are many ways to implement REST Grails makes REST easy with @ R e s o u r c e ! Don't reinvent the wheel, use standard practices.
61. QUESTIONS?
62. REFERENCES Kay, Russell. . Computerworld. 6 Aug 2007. Web Fischer, Ludovico. . Tuts+. 9 Jan 2013. Web Fielding, Roy. . 2000. "Representational State Transfer (REST)" "A Beginner’s Guide to HTTP and REST" Architectural Styles and the Design of Network-based Software Architectures