RESTful "Hypermedia-Services" auf der JVM

REST und Hypermedia APIs sind auch 2015 in aller Munde. Dabei gilt es eigentlich immer wieder die gleichen Prinzipien zu berücksichtigen. Hierzu zählen vor allem der richtige Einsatz von HTTP Status Codes, korrekte Content Negotiation und Caching.

In dieser Session wollen wir die Grundlagen besprechen und diese an praxisnahen Beispielen vertiefen. Hierzu setzen wir mit "liberator" auf eine Clojure Bibliothek, die sich nah an der HTTP Spezifikation befindet und den Entwickler somit optimal unterstützt seine Anwendungsdaten RESTful und HTTP konform als Resourcen anzubieten. Trotz der niedrigen Versionsnummer ist "liberator" auch für nicht Clojuristen einen Blick wert, basiert es doch auf den erprobten Konzepten der Erlang "Webmachine"-Implementierung.

Transcript

1. RESTful "Hypermedia-Services" auf der JVM BEDCon 2015 Michael Vitz (@michaelvitz)
2. RESTful?
3. RPC over HTTP http://martinfowler.com/articles/images/richardsonMaturityModel/overview.png
4. RPC over HTTP http://martinfowler.com/articles/images/richardsonMaturityModel/overview.png
5. RESTful http://martinfowler.com/articles/images/richardsonMaturityModel/overview.png
6. Methods? GET, POST PUT? DELETE? HEAD? OPTIONS? https://tools.ietf.org/html/rfc7231#section-4.3
7. Methods! PUT DELETE HEAD OPTIONS JSF     Play     Spring     Liberator    
8. Status Codes? $ curl -iL playframework.com > HTTP/1.1 200 OK > Server: Play/2.4.3 Scala/2.11.7
9. Status Codes? $ curl -iL -XDELETE playframework.com > HTTP/1.1 404 Not Found > Server: Play/2.4.3 Scala/2.11.7
10. Status Codes! 100-101 200-206 300-305, 307 400-417, 426 500-505 https://tools.ietf.org/html/rfc7231#section-6
11. Status Codes! Support JSF  Play  Spring  Liberator 
12. Content Negotiation? $ curl -H 'Accept: text/plain' V e r s i o n 0 . 1 . 8 F O A A S $ curl -H 'Accept: application/json' { " m e s s a g e " : " V e r s i o n 0 . 1 . 8 " , " s u b t i t l e " : " F O A A S " } http://www.foaas.com/version http://www.foaas.com/version
13. Content Negotiation! Support JSF  Play  Spring  Liberator 
14. Caching? $ curl -i an-resource > HTTP/1.1 200 OK > ETag: 2 $ curl -i an-resource -H 'If-None-Match: 2' > HTTP/1.1 304 Not Modified $ curl -i an-resource -H 'If-Match: 1' --data foo=bar > HTTP/1.1 412 Precondition Failed
15. Caching! Support JSF  Play  Spring  Liberator 
16. RESTful!
17. What about links???
18. Hypermedia?
19. Hypermedia Server generates link Client uses link
20. Nothing more???
21. Nothing more!!!!
22. Step 1: Service Documents
23. < ? x m l v e r s i o n = " 1 . 0 " e n c o d i n g = " U T F - 8 " ? > < s e r v i c e D e s c r i p t i o n x m l : b a s e = " h t t p : / / o m . e x a m p l e . c o m " > < l i n k r e l = " a l l " h r e f = " / o r d e r s / " / > < l i n k r e l = " r e c e i v e d " h r e f = " / o r d e r s / r e c e i v e d / " / > < l i n k r e l = " a c c e p t e d " h r e f = " / o r d e r s / a c c e p t e d / " / > < l i n k r e l = " r e j e c t e d " h r e f = " / o r d e r s / r e j e c t e d / " / > < l i n k r e l = " c a n c e l l e d " h r e f = " / o r d e r s / c a n c e l l e d / " / > < l i n k r e l = " f u l f i l l e d " h r e f = " / o r d e r s / f u l f i l l e d / " / > < l i n k r e l = " c a n c e l l a t i o n s " h r e f = " / c a n c e l l a t i o n s / " / > < l i n k r e l = " r e p o r t s " h r e f = " / r e p o r t s / " / > < / s e r v i c e D e s c r i p t i o n > < ? x m l v e r s i o n = " 1 . 0 " e n c o d i n g = " U T F - 8 " ? > < s e r v i c e D e s c r i p t i o n x m l : b a s e = " h t t p : / / o m . e x a m p l e . c o m " > < l i n k r e l = " a l l " h r e f = " / o r d e r s / " / > < l i n k r e l = " r e c e i v e d " h r e f = " / o r d e r s / r e c e i v e d / " / > < l i n k r e l = " a c c e p t e d " h r e f = " / o r d e r s / a c c e p t e d / " / > < l i n k r e l = " r e j e c t e d " h r e f = " / o r d e r s / r e j e c t e d / " / > < l i n k r e l = " c a n c e l l e d " h r e f = " / o r d e r s / c a n c e l l e d / " / > < l i n k r e l = " f u l f i l l e d " h r e f = " / o r d e r s / f u l f i l l e d / " / > < l i n k r e l = " c a n c e l l a t i o n s " h r e f = " h t t p : / / o m . a r c h i v e . c o m / o r d e r s / " / > < l i n k r e l = " r e p o r t s " h r e f = " / r e p o r t s / " / > < / s e r v i c e D e s c r i p t i o n > { " s e r v i c e D e s c r i p t i o n " : { " b a s e " : " h t t p : / / o m . e x a m p l e . c o m " , " l i n k s " : [ { " r e l " : " a l l " , " h r e f " : " / o r d e r s / " } , { " r e l " : " a l l " , " h r e f " : " / o r d e r s / " } , { " r e l " : " r e c e i v e d " , " h r e f " : " / o r d e r s / r e c e i v e d / " } , { " r e l " : " a c c e p t e d " , " h r e f " : " / o r d e r s / a c c e p t e d / " } , { " r e l " : " r e j e c t e d " , " h r e f " : " / o r d e r s / r e j e c t e d / " } , { " r e l " : " c a n c e l l e d " , " h r e f " : " / o r d e r s / c a n c e l l e d / " } , { " r e l " : " f u l f i l l e d " , " h r e f " : " / o r d e r s / f u l f i l l e d / " } , { " r e l " : " c a n c e l l a t i o n s " , " h r e f " : " / c a n c e l l a t i o n s / " } , { " r e l " : " r e p o r t s " , " h r e f " : " / r e p o r t s / " } ] } }
24. JSON Home { " r e s o u r c e s " : { " h t t p : / / e x a m p l e . o r g / r e l / w i d g e t s " : { " h r e f " : " / w i d g e t s / " } , " h t t p : / / e x a m p l e . o r g / r e l / w i d g e t " : { " h r e f - t e m p l a t e " : " / w i d g e t s / { w i d g e t _ i d } " , " h r e f - v a r s " : { " w i d g e t _ i d " : " h t t p : / / e x a m p l e . o r g / p a r a m / w i d g e t " } , " h i n t s " : { " a l l o w " : [ " G E T " , " P U T " , " D E L E T E " , " P A T C H " ] , " r e p r e s e n t a t i o n s " : [ " a p p l i c a t i o n / j s o n " ] , " a c c e p t - p a t c h " : [ " a p p l i c a t i o n / j s o n - p a t c h " ] , " a c c e p t - p o s t " : [ " a p p l i c a t i o n / x m l " ] , " a c c e p t - r a n g e s " : [ " b y t e s " ] } } } } http://tools.ietf.org/html/draft-nottingham-json-home-03
25. Step 2: Resource Links
26. G E T / o r d e r / 1 2 3 { " o r d e r " : { " d a t e " : " 2 0 1 3 - 0 7 - 0 2 " , " t o t a l " : 1 2 4 0 . 0 2 , " . . . " : " . . . " , " l i n k s " : { " s e l f " : " h t t p : / / e x a m p l e . c o m / o r d e r s / 1 2 3 " , " c o n t a c t s " : " h t t p : / / e x a m p l e . o r g / A 3 B E F 1 " , . . . } } } Your future extensions
27. Step 3: State Transition Links
28. created processing cancelled shipped ship commit cancel delete update commited process failed fail { " o r d e r " : { " s t a t e " : " c r e a t e d " , " . . . " : " . . . " , " l i n k s " : { " c a n c e l " : " h t t p : / / . . . " , " c o m m i t " : " h t t p : / / . . . " , " d e l e t e " : " h t t p : / / . . . " , . . . } } }
29. Step 4: Provide recipes for URIs
30. < f o r m a c t i o n = " h t t p : / / e x a m p l e . c o m / s e a r c h " m e t h o d = " G E T " > S e a r c h f o r : < i n p u t t y p e = " t e x t " n a m e = " q u e r y " > < i n p u t t y p e = " s u b m i t " > < / f o r m > h t t p : / / e x a m p l e . c o m / s e a r c h ? q u e r y = x y z { " l i n k s " : { " s e a r c h " : { " t e m p l a t e " : " h t t p : / / e x a m p l e . c o m / s e a r c h ? q = { q u e r y } " } } } RFC 6570: URI Template [https://tools.ietf.org/html/rfc6570]
31. < f o r m a c t i o n = " h t t p : / / e x a m p l e . c o m / a d d " m e t h o d = " P O S T " > < l a b e l f o r = " f i r s t " > F i r s t : < / l a b e l > < i n p u t t y p e = " t e x t " n a m e = " f i r s t " i d = " f i r s t " > < l a b e l f o r = " l a s t " > L a s t : < / l a b e l > < i n p u t t y p e = " t e x t " n a m e = " l a s t " i d = " l a s t " > < l a b e l f o r = " b i r t h d a y " > B i r t h d a y : < / l a b e l > < i n p u t t y p e = " d a t e " n a m e = " b i r t h d a y " i d = " b i r t h d a y " > < i n p u t t y p e = " s u b m i t " > < / f o r m > { " l i n k s " : { " a d d " : { " h r e f " : " h t t p : / / e x a m p l e . c o m / a d d " , " t e m p l a t e " : { " f i r s t " : " . . . " , " l a s t " : " . . . " , " b i r t h d a y " : " . . . " } } } }
32. Hypermedia! Support JSF  Play  Spring  Liberator 
33. Hypermedia!
34. http://clojure-liberator.github.io/
35. Liberator Version: 0.13 Inspired by: Erlang's Webmachine
36. Controller? $ grep -ic controller rfc723{0..7} > 0
37. Resource! ( d e f r e s o u r c e h e l l o - w o r l d : a v a i l a b l e - m e d i a - t y p e s [ " t e x t / p l a i n " ] : h a n d l e - o k " H e l l o , w o r l d ! " )
38. Decision Graph: System https://github.com/for-GET/http-decision-diagram
39. Decision Graph: System https://github.com/for-GET/http-decision-diagram
40. Decision Graph: Request https://github.com/for-GET/http-decision-diagram
41. Decision Graph: Request https://github.com/for-GET/http-decision-diagram
42. Decision Graph: Accept https://github.com/for-GET/http-decision-diagram
43. Decision Graph: Retrieve https://github.com/for-GET/http-decision-diagram
44. Decision Graph: Create https://github.com/for-GET/http-decision-diagram
45. Decision Graph: Response https://github.com/for-GET/http-decision-diagram
46. Decision Graph: Retrieve https://github.com/for-GET/http-decision-diagram
47. Decision Graph: Precondition https://github.com/for-GET/http-decision-diagram
48. Decision Graph: Process https://github.com/for-GET/http-decision-diagram
49. Decision Graph: Response https://github.com/for-GET/http-decision-diagram
50. Liberator: Example ( A N Y " / c h o i c e " [ ] ( r e s o u r c e : a v a i l a b l e - m e d i a - t y p e s [ " t e x t / h t m l " ] : e x i s t s ? ( f n [ c t x ] ( i f - l e t [ c h o i c e ( g e t { " 1 " " s t o n e " " 2 " " p a p e r " " 3 " " s c i s s o r s " } ( g e t - i n c t x [ : r e q u e s t : p a r a m s " c h o i c e " ] ) ) ] { : c h o i c e c h o i c e } ) ) : h a n d l e - o k ( f n [ c t x ] ( f o r m a t " < h t m l > Y o u r c h o i c e : % s " ( g e t c t x : c h o i c e ) ) ) : h a n d l e - n o t - f o u n d ( f n [ c t x ] ( f o r m a t " < h t m l > N o v a l u e f o r o p t i o n : % s " ( g e t - i n c t x [ : r e q u e s t : p a r a m s " c h o i c e " ] " " ) ) ) ) )
51. Similar Frameworks webmachine webmachine-ruby Webster
52. Summary RESTful Hypermedia HTTP decision graph Frameworks/Libraries
53. Thank you! Questions? Michael Vitz michael.vitz@innoq.com @michaelvitz https://speakerdeck.com/michaelvitz