Introduction to REST and Jersey


Published on

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Introduction to REST and Jersey

  1. 1. REST and Jersey Introduction Chris Winters Pittsburgh Java User Group 21 April 2009    
  2. 2. Did you update the URLs? (slide 13: update with IP so people can access)    
  3. 3. Anyone want to vent?    
  4. 4. Who am I?  (not the male model)  Dad of awesome two year­old  Software Architect at Vocollect Healthcare Systems  Most experience on very small teams  AccuNurse: voice­assisted care for nursing homes  We use many, many opensource libraries  Not a REST expert, just very interested    
  5. 5. REST  Representational State Transfer  Defined in Roy Fielding dissertation  One primary implementation to­date: web + HTTP  Why the interest?  Web: ubiquitous, scalable, enabling platform    
  6. 6. HTTP Success  Text­based!  Simple!  Universal!  Clients and servers aren't tightly bound    
  7. 7. HTTP Success, Deeper  Supports very simple + very complex apps  Lots of options to scale, not just single path  Stateless by default  ...which means it's easy to test  Those aren't documents, they're resources!  ...and a resource ~~ distributed object    
  8. 8. So? I'm not building Amazon  Simplicity  Flexibility  Evolvability  Testability  Discoverability  ...all good things, not related to scaling    
  9. 9. A few initial warnings  Resource­oriented very useful approach  ...tough to purely implement with browsers  ...and it requires some mind bending  Still worthwhile!  REST != HTTP (but we'll use it anyway)  Show a good deal of code    
  10. 10. Map  What is REST?  REST in Java  What is REST?  REST in Java  ...    
  11. 11. In the beginning...  "REST" was created looking back at HTTP  But the guy who created REST  also helped create HTTP  His dissertation is very readable!    
  12. 12. REST boiled down  Give every "thing" an ID  Link things together  Use standard methods  Resources with multiple representations  Communicate statelessly   (from Stefan Tilkov, awesome REST guy)  
  13. 13. Our dorky little application  Notem: record notes, become group memory  Potential: Dynamic notes (~~IRC bots)    
  14. 14. Access Notem now!  Crude interface, but easy to navigate  Web:  Data:  Distribution:  Slides:    
  15. 15. Notem resources  Resource = 'state with URI' (lots else too)  Every note  Every collection of notes   Initial workspace    
  16. 16. Jersey intro  RI of JSR­311, Sun  folks primary on team  Heavily reliant on  annotations  Skeptical before, but  I'm a believer!    
  17. 17. Jersey Extensibility  Highly extensible  @Provider means: "Hey Jersey, plug this in!"  Examples: TemplateProvider, JAXB items  Contextual items can be injected with @Context  Contextual: UriInfo, HttpHeaders, Security  Interesting bit: getting contextual data down to  objects manipulated by other frameworks (JAXB)     
  18. 18. RBD #1: An ID for everything  ID == URI  I == Identifier, L == Location  Globally unique, routeable identifier  They don't have to be pretty!  'Thing' can have broad meaning:  Collection of other things  Process that can report state    
  19. 19. 'Routeable' identifier?  Most think of ID as primary key: 42  Maybe: table:ID  Maybe: server:database:table:ID  ...where 'server' lookup into local registry  Even if that worked, what would it return?    
  20. 20. URI works everywhere  Built on top of basic plumbing (DNS, hostnames)  Protocol specification built­in (http://, ftp://)  Abstraction built­in too:  what I want (URL)  how to shuffle it around (HTTP)  not how to fetch/generate    
  21. 21. Common misconception: URI design  "Hackable" URIs nice, not necessary  Only constraint is that they're unique  BDUF: Lay out entire URI scheme  Agile: Define as you go, refactor mercilessly    
  22. 22. RBD #1: Jersey help  Every resource has an enforced unique URI  ...not much beyond that    
  23. 23. RBD #2: Link things together  Use server­provided URIs as references  Clients building URIs is a common mistake!   Limit URI templates to query­building hints  HATEOAS    
  24. 24. URI templates?  On server­side, hugely useful  Declare variables from URI, map to method params  Also available: regex matching    
  25. 25. HATEOAS?  Hypertext As The Engine  of Application State  RTF uses "the hypermedia  constraint" instead    
  26. 26. HATEOAS!  Server­controlled links define what clients can do  You can move hosts!  Shard data!  Change URIs!  And potentially all this without taking systems down    
  27. 27. HATEOAS + refactoring  Refactoring another benefit of HATEOAS  Client dependent on server for state transitions  ...immediately change  client behavior  Seems simple, but  we're just used to it  Start simple, grow  organically    
  28. 28. Clients cannot assume resource structure!  Everything the client can do is created by server  Client and server can know beforehand about media  types and types of transitions  Different 'rel' types in 'link' element...  OPTIONS informs about allowed methods  Jersey: application.wadl  Ways to know you're not doing HATEOAS...    
  29. 29. 'REST endpoint'  “Here's the endpoint for our REST API”  REST exposes resources many URIs  Not actions via a few    
  30. 30. URI scheme up front  “Here are all the URIs in our REST API”  ...implies out­of­band info important to app flow   Client discover resources moving through system  Publishing your URI structure is coupling    
  31. 31. Clients parse URIs  “Here's the data you'll need from the URI”  URI is opaque identifier  Content of resource should be standalone  Example: /blog/2009/04/20/my_hair_isnt_that_bad  Does content have date in it too?  API forces client to parse URIs: more coupling    
  32. 32. URIs name actions  Flickr API URIs name actions vs resources /services/rest/?method=flickr.test.echo...  REST has uniform interface! (more later)  Specifying methods/actions == RPC    
  33. 33. RPC + Coupling "Today's example is the SocialSite  REST API. That is RPC. It screams RPC.  There is so much coupling on display that it  should be given an X rating." ­ Roy Fielding,  REST APIs must be hypertext driven    
  34. 34. So bad about coupling?  Evolvability  Dependencies on structure inhibits evolution  Do you expose your database tables?  Or your libraries?  If you choose to, it's a trade­off  ...just one that REST explicitly chooses differently    
  35. 35. URIs and the real world  Easier to publish API that says "Send datablob A to  URI B and X will occur"  IMO REST client development, generic or  otherwise, still early days...  do what you can    
  36. 36. More HATEOAS  Lots of recent discussion on this:  rest­discuss posts (including Solomon Duskis)  Subbu: "On Linking"  Craig McC on Sun Cloud API    
  37. 37. Generating links  Underdeveloped area  Componentize link generation?  Should a resource generate its own URI?  How to inject context (host/port) down?  Manipulate rules at runtime?  Example: Reference all Employee objects at host frodo  Example: ...all Buildings with area > 25000 to gondor    
  38. 38. RBD #2: Jersey Help “...this is probably the hardest area. JAX­RS  provides a bunch of ways to construct URIs but  there is no such URI binding facility with a  modeling API, such as JAXB.” ­ Paul Sandoz InfoQ announcement: JSR 311 Final    
  39. 39. RBD #3: Use standard methods  AKA, 'uniform interface'  Methods never vary based on resources  Key constraint that allows intermediaries to function  Google knows GET is safe, can spider your site  ...except when it's not safe    
  40. 40. Dangers of unsafe GET "[The Alexa toolbar] logged into the  administrative area and followed the  'delete' link for every entry," the admin  says. "My dumb­ass boss still didn't  want to uninstall Alexa ­­ could have  strangled the man." ­ Stupid user tricks 3: IT admin follies    
  41. 41. Methods have semantics  Key difference from RPC systems  HTTP defines what GET/PUT/DELETE mean  ...on any resource  Idempotent: invoke multiple times with same effect  What will service.updateOrder() do if called twice?  What about service.takeOrder()?  POST is the catch­all, the 'process' method    
  42. 42. Standard methods + idempotency Method Purpose Idempotent? Safe? =================================================== GET Retrieve representation Y Y PUT Provide representation Y N POST Create/extend resource N N DELETE Delete resource Y N HEAD GET minus body Y Y OPTIONS Find methods for resource Y Y    
  43. 43. Which does RPC-over-HTTP use? Method Purpose Idempotent? Safe? =================================================== POST Create/extend resource **N** **N**    
  44. 44. Benefits of standard methods  Original name of REST: HTTP Object Model   All objects on the web can be manipulated similarly  Implementation hiding: what language? what  model? who cares?  Generic invocation: no need to generate code for  actions, only data    
  45. 45. Where are my methods? Constraint!  Yes, GET/PUT/DELETE/POST are constraints  Ask anyone who writes: can sharpen focus  Thinking in uniform  methods key to ROA    
  46. 46. Nouning verbs  One pattern for adapting action­centric designs is  [1] nouning verbs  Canonical example: transactions  Treat the transaction as a resource with status  Reference the resource in your actions – client  maintains application state! (more later)  [1] Because “resourcing verbs” sounds too Office Space-y    
  47. 47. Nouning Transactions    
  48. 48. TMTOWTDI  Instead of referencing the resource, maybe I could   POST different resources to the transaction?  ...transaction resource could passthru resources  There are multiple ways to do it: that's the point  Actions­as­resources takes a while, but useful    
  49. 49. RBD #3: Jersey support  Awesome  Annotations for all major HTTP methods  @HEAD coming in JAX­RS 1.1    
  50. 50. Sidetrack: Jersey resources  “How does Jersey discover my resources?”  Define Application which explicitly names  Tell Jersey to scan your package  Wire into your DI framework (Spring/Guice)  Also true of @Provider implementations    
  51. 51. Enabling evil “Granted the abstraction of this messaging  infrastructure led to bindings and dependencies  that we are trying to get out of today, but that  doesn't make RPC evil, it's the technologies and  'programming style' that resulted from RPC that  have become evil.” ­ Ebenezer Ikonne    
  52. 52. Avoiding evil  Great presentation by Steve Vinoski on RPC history  discusses RPC issues  Summary: Avoid  ...if remote looks local, you will eventually lose    
  53. 53. Current distributed systems  Highly dependent on code generation, stubs  Winds up treating  data­over­wire as opaque   ...will be difficult to reuse  on the same platform  cross­platform? ha!    
  54. 54. Defining service contracts “Using a regular programming language to define  supposedly abstract interfaces greatly increases  the chances that language­specific constructs will  leak into the contract.” ­ Steve Vinoski    
  55. 55. Problems with remote calls  RPC should have high barrier to entry: it's hard!  Very tight coupling  Synchronization required (pre­3.0 entity beans?)  Restricted failure modes  Closed protocol (typically)  And...    
  56. 56. Fallacies of distributed computing 1) The network is reliable. 2) Latency is zero. 3) Bandwidth is infinite. 4) The network is secure.    
  57. 57. Fallacies of distributed computing 5) Topology doesn't change. 6) There is one administrator. 7) Transport cost is zero. 8) The network is homogeneous. More: Fallacies of Distributed Computing Explained    
  58. 58. RPC hopes  System that solves problems inherent in distributed  computing.  Examples Vinoski uses: REST and Erlang    Make explicit tradeoffs to work around limitations  Echoing Fielding dissertation: it's all about tradeoffs    
  59. 59. Focus on data!  All this means: you're pushing the problem to data.  This is good! You wind up there anyway.     
  60. 60. Sending data  Historically representation tied to RPC system  IIOP, DCE, RMI, SOAP + XML  Instead, your data identified by media type  Allows you to separate concerns:  Library for processing media type  Library for moving data through logic    
  61. 61. RBD #4: Multiple representations  'Resource' is an abstract entity, a concept  You only interact with representations  With HTTP, content negotiation informs    
  62. 62. HTTP: Accept  Every request has an 'Accept' HTTP header  Useful tools for seeing this in browser  Useful tools for specifying from CLI  RESTful service provides appropriate representation    
  63. 63. Representations in Notem  Three main ones, not applicable in all cases  text/html, application/xml, application/json  When using programmatic HTTP access it's easier  to control     
  64. 64. Representation communicates resource  Others we could use?    
  65. 65. Representation communicates resource  audio/mpeg: output of TTS engine  application/ssml+xml: Speech synthesis markup (so  your TTS can speak the note)  application/morse­code (madeup)  Representations can be derived: not every one needs  to be PUTable    
  66. 66. Designing representations  Behooves you to use widely known media types  "Get over the idea that your domain is a unique and  special snowflake"  See Bill de Hora  "Snowflake APIs"    
  67. 67. Media types “A REST API should spend almost all of its  descriptive effort in defining the media type(s)  used for representing resources and driving  application state...” ­ Roy Fielding,  REST APIs must be hypertext driven    
  68. 68. RBD #4: Jersey support  Awesome  Declare @Produces and @Accepts for class or  methods  Jersey parses Accept header and dispatches to the  right one    
  69. 69. What's a valid return value?  No interface required  One known: status  + cookies, etag, entity...  Others: try to match with MessageBodyWriter  ...including list/array, though may be useful to have  explicit 'collection representation' to model  additional state    
  70. 70. MessageBodyWriter examples  byte[] ­> ByteArrayProvider  Viewable ­> ViewableMessageBodyWriter ­>  TemplateProvider  JAXB­registered object ­>  JSONJAXBElementProvider ||  XMLJAXBElementProvider    
  71. 71. Brief digression on JAXB  Nifty technology!  Tutorials focus on XML schemas and code  generation  Skip all that, basic use is pretty easy    
  72. 72. Marshalling sucks  How many libraries? JiBX, XmlBeans, XStream...  No silver bullet  Marshalling always sucks, anyone who says  differently is selling you something    
  73. 73. RBD #5: Communicate statelessly “...communication must be stateless in  nature...such that each request from client to  server must contain all of the information  necessary to understand the request, and cannot  take advantage of any stored context on the  server. Session state is therefore kept entirely on  the client.” ­ Roy Fielding, p.78­9.    
  74. 74. Benefits of statelessness  Caching  Scale out, not up  Simple in some senses, not others    
  75. 75. Different types of state  Client: Application state is 'where' you are  Server: Resource state is what you're manipulating  Possible to represent application state as resource?    
  76. 76. Examples of state  Phone conversation: all 'application' state  Client/server app: server holds open transactions,  current 'screen', relies on open connection  Web app: current page of results, shopping cart,  current 'item' being worked on, GUI  customizations...    
  77. 77. Shopping cart example  Assuming a fully featured client  might we design a RESTful shopping cart?    
  78. 78. RBD #5: Jersey support  Really an implementation detail  Jersey helps you DTRT, but you're free to break it    
  79. 79. Why caching?  The fastest DB query is the one never executed  Nearly all applications are read­mostly: optimize!  Transparently­added caching even better  (view 'Many intermediaries image')  The network is not transparent    
  80. 80. Faking statefulness (test)  Form data just key/value pairs  Cookies just text  HTTP Authentication just a header    
  81. 81. 'Architectural Style' “An architectural style is a coordinated set of  architectural constraints that restricts the  roles/features of architectural elements and the  allowed relationships among those elements  within any architecture that conforms to that style.” ­ Roy Fielding, p. 13    
  82. 82. 'Architectural Style'  Abstraction for component interaction  An architecture reflects its environment  ...but hard to compare those from different  environments   It is not a set of defined messages    
  83. 83. 'Architecture Style'  Alan Dean:  A style can be applied to many different architectures.  An architecture can consist of many different styles.    
  84. 84. Pieces of the Style  Client/Server (separation of concerns)  Stateless communication  Caching  Uniform interface  Layered system  Code on demand    
  85. 85. Style implications  You will not be buying a 'REST Toolkit'  One level up from tools allows evaluation of fit for  purpose  Fielding dissertation opens with reference to Monty  Python sketch : "It might very well be the best slaughterhouse design ever  conceived, but that would be of little comfort to the  prospective tenants as they are whisked along hallways  containing rotating knives." ­ Fielding    
  86. 86. Other styles  POX: Plain old XML: not bad <em>a priori</em>,  but,  ... typically everything goes through POST (XML­RPC)  MEST ('processThis()', see Jim Webber for more)  "Low REST" vs "High REST" (RTF says it's  hogwash)    
  87. 87. Now what?  Evolvability is underrated  Distributed systems are hard  Try it! Building even a small system will introduce  new 'resources' that you probably haven't thought of  Jersey is proof that JSRs can work    
  88. 88. Thank you!    
  89. 89. Resources on REST Collected on my site, slides are terrible for this:    
  90. 90. Attributions  Testudo Shrug  Tinkertoy Sticks   I hate zombies  Mike Tomlin (Gregory Shamus/Getty Images)  I Hate Mondays