Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
RESTRESTTheory and PracticeVladimir Tsukur / Design Engineer & Team Lead @GlobalLogic, Partner @FrostDigital   2012
REST 1Theory                2
RESTREpresentational State Transfer          3
RESTREpresentational State Transfer          4
REST«A software architecture is an abstraction   of the run-time elements of a softwaresystem during some phase of its ope...
RESTArchitecture Elements               Components               Components                Components                     ...
RESTArchitecture Elements                                  SQL                      DAO               DBREpresentational S...
REST«An architectural style is a coordinated setof architectural constraints that restricts theroles/features of architect...
REST               REST = styleREpresentational State Transfer          9
RESTIt is actually a hybrid style ;)REpresentational State Transfer          10
REST    WWW Requirements First‣    Low Entry-barrier      ‣         Hypermedia‣    Extensibility          ‣         Prepar...
REST                        REST                      ConstraintsREpresentational State Transfer            12
REST1. Client - Server+ Separation of concerns+ UI portability+ Improved scalabilityREpresentational State Transfer       ...
REST2. Stateless+ Visibility                      - Performance+ Reliability                     - Consistency+ Scalabilit...
REST3. Cache+ Efficiency                       - Reliability+ Scalability+ UP PerformanceREpresentational State Transfer   ...
RESTClient-Cache -Stateless-Server =                                  <                                  1994REpresentatio...
RESTWeb < 1994- Static documents- CERN libwww common library- No consistent set of semanticsfor all resourcesREpresentatio...
REST4. Uniform Interface+ Simplicity                      - Efficiency+ Visibility+ EvolvabilityREpresentational State Tran...
REST5. Layered System+ Simplicity                      - UP Performance+ Scalability+ EvolvabilityREpresentational State T...
REST6. [Code-on-Demand]+ Client Simplicity               - Visibility+ ExtensibilityREpresentational State Transfer       ...
RESTRESTREpresentational State Transfer          21
REST                  REST              Data ElementsREpresentational State Transfer          22
RESTResourcesREpresentational State Transfer          23
RESTResources      <a href=’                   ’>Winnie</a>REpresentational State Transfer                         23
REST«A resource is a conceptual mapping to a     set of entities, not the entity that    corresponds to the mapping at any...
RESTResources                      => {}                      => static:                      => dynamic:REpresentational ...
RESTResources                                  M R(t)={                                      ids and/or                   ...
RESTResources            1.0                   1.1   2.0   «latest»REpresentational State Transfer                        ...
RESTResources            1.0                   1.1   2.0 != «latest»REpresentational State Transfer                       ...
RESTResources      + Generality      + Late binding of reference to               implementation (request-time)      +    ...
RESTResource IDsREpresentational State Transfer          29
RESTResource IDs http://www.teddybear.org/winnieREpresentational State Transfer          29
RESTResource IDs   «Since centralized link servers are ananathema to the immense scale and multi- organizational domain re...
RESTResource Representations Content-Type: text/plain Thu Jul 05 2012 20:05:15 GMT+0300 (EEST)Content-Type: text/xml<curre...
RESTResource Representations • Data      Thu Jul 05 2012 20:05:15 GMT+0300 (EEST) • Metadata     Content-Type: text/plain ...
RESTMetadata  • Name-Value Pairs  • Resource Metadata      Allow: GET, HEAD, OPTIONS  • Representation Metadata      Conte...
RESTControl Data• Defines purpose of the message     GET• Used to parameterize request         (e.g. caching)     If-Modifi...
RESTMedia Types • Data Format = Media Type • Intention   • Automated processing   • Rendered / viewed by a user   • Both •...
RESTConnectors • Client • Server • Cache   • Shared (Akamai)   • Non-shared (browser) • Resolver (DNS) • Tunnel (SSL)REpre...
RESTComponents  •       Origin Server  •       Gateway  •       Proxy  •       User AgentREpresentational State Transfer  ...
REST                                   2                                  PracticeREpresentational State Transfer         ...
RESTREpresentational State Transfer          39
RESTBooking Lifecycle                                    update               cancel                                      ...
REST                                  CRUDREpresentational State Transfer                 41
REST    Create New BookingPOST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-id»: ...
REST    Create New BookingPOST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-id»: ...
RESTPOST?REpresentational State Transfer          43
RESTPOST?       • Server determines resource URI       • We are changing server state               (POST is not safe!)   ...
REST    Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     ...    ...
REST    Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     ...    ...
REST    Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     ...    ...
REST    Creation Failure - 500POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-i...
REST    Creation Failure - 500POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-i...
RESTCreation Failure - 500        • Forward progress is tricky                (booking created or not?)                • R...
REST    Creation Failure - 503POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-i...
REST                                  CRUDREpresentational State Transfer                 50
RESTReading BookingGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1 200 OK ...
RESTGET?       • No side effects (GET is safe!)       • Resubmitting will return the               same result if resource...
RESTReading Booking (Later)GET /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1...
RESTReading Booking - 404GET /bookings/mars HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1 4...
REST                                  CRUDREpresentational State Transfer                 55
REST    Updating BookingPUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «user-id»...
RESTPUT?REpresentational State Transfer          57
RESTPUT?       • Client determines resource URI       • We are changing server state               (PUT is not safe!)     ...
REST    Updating Booking - 204PUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «us...
RESTPUT: 200 or 204?                • 200 more descriptive and                        confirms server-side state           ...
REST    Updating Booking - 409PUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{     «us...
REST      PUT or       POSTfor Create/Update?REpresentational State Transfer          61
RESTPUT/POST Guidelines   • Use POST to create a resource identified by            a service-generated URI   •        Use P...
REST                  Partial / Bulk                    Updates?REpresentational State Transfer           63
RESTPartial Update Strategies1.     Encapsulate «partial» into its own sub-resource       and invoke PUT on it       • ......
REST    Partial Update - POSTPOST /bookings/9111/dates HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{  ...
REST Partial Update - PUTPUT /bookings/9111/from HTTP/1.1Host: www.booking-rest.comContent-Type: text/plain2012-07-22     ...
RESTBulk Update StrategiesREpresentational State Transfer          67
RESTBulk Update Strategies1.     HTTP Pipelining       1. Not well supported :(       2. Innappropriate for non-idempotent...
RESTBulk Update - POSTPOST /bookings/cancelled HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{    «ids»:...
REST                                  CRUDREpresentational State Transfer                 69
RESTDELETE Booking - 204DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1...
REST DELETE Booking - 200DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                   HTTP/1...
RESTDELETE Booking - 404DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1...
RESTDELETE Disallowed - 405DELETE /current-time HTTP/1.1Host: www.time.com                                  HTTP/1.1 405 M...
REST               Is it REST API?REpresentational State Transfer          74
REST               Is it REST API?                      NOREpresentational State Transfer          74
REST                       Richardson                        Maturity                          ModelREpresentational State...
RESTRMMREpresentational State Transfer          76
REST    Level 0 - CreatePOST /bookingService HTTP/1.1Content-Type: application/json{     «create»: {       «hotel-id»: «pa...
REST    Level 0 - RetrievePOST /bookingService HTTP/1.1Content-Type: application/json{     «retrieve»: {       «id»: «9111...
REST    Level 0 - ConfirmPOST /bookingService HTTP/1.1Content-Type: application/json{     «confirm»: {       «id»: «9111», ...
RESTLevel 0REpresentational State Transfer          80
RESTLevel 01.     Single URI endpoint2.     Single HTTP method3.     Uses HTTP as transport, not app protocol4.     Does n...
RESTLevel 01.     Single URI endpoint2.     Single HTTP method3.     Uses HTTP as transport, not app protocol4.     Does n...
REST    Level 1 - CreatePOST /booking HTTP/1.1Content-Type: application/json{     «create»: {       «hotel-id»: «paris:ber...
REST    Level 1 - RetrievePOST /booking HTTP/1.1Content-Type: application/json{     «retrieve»: {       «id»: «9111»     }...
REST    Level 1 - ConfirmPOST /confirmation HTTP/1.1Content-Type: application/json{     «create»: {       «id»: «9111»,    ...
RESTLevel 1REpresentational State Transfer          84
RESTLevel 11. Multiple resources2. Single HTTP method3. Action in URI or payloadREpresentational State Transfer          84
RESTLevel 11. Multiple resources2. Single HTTP method3. Action in URI or payload               Flickr «REST» API,         ...
RESTLevel 2REpresentational State Transfer          85
RESTLevel 21. Many URIs2. Many verbs3. We’ve designed it already ;)REpresentational State Transfer          85
RESTLevel 21. Many URIs2. Many verbs3. We’ve designed it already ;)              Amazon S3               Twitter API      ...
RESTLevel 2 APIs                                     HTTP-based Type 1   HTTP-based Type 2     Identification of Resources ...
REST                                  Level 3?REpresentational State Transfer                     87
REST«If the engine of application state (and  hence the API) is not being driven byhypertext, then it cannot be RESTful an...
REST                            HATEOASREpresentational State Transfer              89
RESTBrowsing                           Follow links                      Change application state                      Mov...
RESTInteractionGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1 200 OK     ...
RESTInteractionGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com                                  HTTP/1.1 200 OK     ...
RESTResource State1.     Information belonging to the resource2.     Links to related resources3.     Possible transition(...
RESTDomain Application Protocol    Legal interactions between consumer and a set      of resources involved in a business ...
REST                    HTTP/1.1 200 OK                    Content-Type: application/json                    {            ...
REST                    HTTP/1.1 200 OK                    Content-Type: application/json                    {            ...
RESTURI Templates      - Service is bound to honoring      these templates forever (and URIs      do change!)      - You’r...
REST                 Single entry-                  point URI(s)REpresentational State Transfer          96
REST                 Single entry-                  point URI(s)                      http://www.booking-rest.com/bookings...
RESTLoose CouplingUnderstanding of specific URI structure‣ Change URI shapes‣ Relocate resources todifferent servers (parti...
RESTLoose Coupling       Semantics of a «link»!!!REpresentational State Transfer          98
RESTLoose Coupling       Semantics of a «link»!!!                «link» = hypermedia controlREpresentational State Transfe...
RESTHypermedia Control           HTTP/1.1 200 OK           Content-Type: application/json           {               «user-...
RESTHypermedia Control          {              ...              «confirmation»: «http://www.booking-rest.com/confirmation/...
RESTHypermedia Control          {              ...              «confirmation»: «http://www.booking-rest.com/confirmation/...
RESTBetter Hyperm Control           HTTP/1.1 200 OK           Content-Type: application/json           {               «us...
RESTMedia Type            HTTP/1.1 200 OK            Content-Type: application/json            {                «user-id»:...
RESTMedia Type            HTTP/1.1 200 OK            Content-Type: application/json            {                «user-id»:...
REST          Content-Type drives           processing of the               payload,         NOT the payload itselfREprese...
RESTMedia Type            HTTP/1.1 200 OK            Content-Type: application/json            {                «hotel-id»...
RESTMedia Type            HTTP/1.1 200 OK            Content-Type: application/json            {                «hotel-id»...
RESTBetter Media Type            HTTP/1.1 200 OK            Content-Type: application/vnd.booking+json            {       ...
REST                Should we give              each representation                 a media type?REpresentational State Tr...
RESTMedia Types /Representations‣ Usually there is NO 1:1 relationship betweenmedia type and representation‣ Usually havin...
RESTCreate New Booking                HTTP/1.1 201 Created                                  Content-Type: application/vnd....
REST«link»‣ URI - identifies a resource with which theconsumer can interact to progress the applicationprotocol‣ rel - cont...
REST    Confirm BookingPOST /confirmation/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/vnd.booking+json...
REST «REST doesn’t eliminate the need for aclue. What REST does is concentrate that   need for prior knowledge into readil...
REST«... It has value because it is far easier tostandardize representation and relation types than it is to standardize o...
REST                        VersioningREpresentational State Transfer             113
REST1. Version in URIREpresentational State Transfer          114
REST1. Version in URI                     http://www.booking-rest.com/v1/bookingsREpresentational State Transfer          ...
REST1. Version in URI                     http://www.booking-rest.com/v1/bookings    • /v1/bookings/9111 != /v2/bookings/9...
REST2. Version in Media TypeREpresentational State Transfer          115
REST2. Version in Media Type    • Another representation of /bookings/9111?        Yes!    • Should client support both /v...
REST2. Version in Media Type                 application/vnd.booking.v2+json                 application/vnd.booking+json;...
REST3. Version in HeaderREpresentational State Transfer          116
REST3. Version in Header                                  X-REST-API-Version: 2.0REpresentational State Transfer          ...
REST3. Version in Header                                  X-REST-API-Version: 2.0      Also fine but can be filtered out by ...
REST                  TransactionsREpresentational State Transfer          117
RESTTransactions1.     If you need transactions, treat them as       corresponding resources       1. Create transaction a...
RESTTransactionPOST /transfer HTTP/1.1Host: www.money-rest.com                                  HTTP/1.1 201 Created      ...
REST                    Frameworks                       (Java)REpresentational State Transfer          120
RESTThanks!Questions?                    121
Upcoming SlideShare
Loading in …5
×

REpresentational State Transfer

3,208 views

Published on

Published in: Technology, Business
  • Be the first to comment

REpresentational State Transfer

  1. 1. RESTRESTTheory and PracticeVladimir Tsukur / Design Engineer & Team Lead @GlobalLogic, Partner @FrostDigital 2012
  2. 2. REST 1Theory 2
  3. 3. RESTREpresentational State Transfer 3
  4. 4. RESTREpresentational State Transfer 4
  5. 5. REST«A software architecture is an abstraction of the run-time elements of a softwaresystem during some phase of its operation» Roy T. Fielding, 2000 REpresentational State Transfer 5
  6. 6. RESTArchitecture Elements Components Components Components Data ConnectorsREpresentational State Transfer 6
  7. 7. RESTArchitecture Elements SQL DAO DBREpresentational State Transfer 7
  8. 8. REST«An architectural style is a coordinated setof architectural constraints that restricts theroles/features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style» Roy T. Fielding, 2000 REpresentational State Transfer 8
  9. 9. REST REST = styleREpresentational State Transfer 9
  10. 10. RESTIt is actually a hybrid style ;)REpresentational State Transfer 10
  11. 11. REST WWW Requirements First‣ Low Entry-barrier ‣ Hypermedia‣ Extensibility ‣ Prepare for change‣ Distributed Hypermedia ‣ Large-grain data transfer‣ Internet-scale ‣ Anarphic scalability ‣ Independent deployment REpresentational State Transfer 11
  12. 12. REST REST ConstraintsREpresentational State Transfer 12
  13. 13. REST1. Client - Server+ Separation of concerns+ UI portability+ Improved scalabilityREpresentational State Transfer 13
  14. 14. REST2. Stateless+ Visibility - Performance+ Reliability - Consistency+ ScalabilityREpresentational State Transfer 14
  15. 15. REST3. Cache+ Efficiency - Reliability+ Scalability+ UP PerformanceREpresentational State Transfer 15
  16. 16. RESTClient-Cache -Stateless-Server = < 1994REpresentational State Transfer 16
  17. 17. RESTWeb < 1994- Static documents- CERN libwww common library- No consistent set of semanticsfor all resourcesREpresentational State Transfer 17
  18. 18. REST4. Uniform Interface+ Simplicity - Efficiency+ Visibility+ EvolvabilityREpresentational State Transfer 18
  19. 19. REST5. Layered System+ Simplicity - UP Performance+ Scalability+ EvolvabilityREpresentational State Transfer 19
  20. 20. REST6. [Code-on-Demand]+ Client Simplicity - Visibility+ ExtensibilityREpresentational State Transfer 20
  21. 21. RESTRESTREpresentational State Transfer 21
  22. 22. REST REST Data ElementsREpresentational State Transfer 22
  23. 23. RESTResourcesREpresentational State Transfer 23
  24. 24. RESTResources <a href=’ ’>Winnie</a>REpresentational State Transfer 23
  25. 25. REST«A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.» Roy T. Fielding, 2000REpresentational State Transfer 24
  26. 26. RESTResources => {} => static: => dynamic:REpresentational State Transfer 25
  27. 27. RESTResources M R(t)={ ids and/or representations }REpresentational State Transfer 26
  28. 28. RESTResources 1.0 1.1 2.0 «latest»REpresentational State Transfer 27
  29. 29. RESTResources 1.0 1.1 2.0 != «latest»REpresentational State Transfer 27
  30. 30. RESTResources + Generality + Late binding of reference to implementation (request-time) + Allows to reference concept, not some singular representationREpresentational State Transfer 28
  31. 31. RESTResource IDsREpresentational State Transfer 29
  32. 32. RESTResource IDs http://www.teddybear.org/winnieREpresentational State Transfer 29
  33. 33. RESTResource IDs «Since centralized link servers are ananathema to the immense scale and multi- organizational domain requirements of the Web, REST relies instead on the authorchoosing a resource identifier that best fitsthe nature of the concept being identified.» Roy T. Fielding, 2000REpresentational State Transfer 30
  34. 34. RESTResource Representations Content-Type: text/plain Thu Jul 05 2012 20:05:15 GMT+0300 (EEST)Content-Type: text/xml<current-time>1341095876929</current-time>REpresentational State Transfer 31
  35. 35. RESTResource Representations • Data Thu Jul 05 2012 20:05:15 GMT+0300 (EEST) • Metadata Content-Type: text/plain • [Metadata to describe the metadata]REpresentational State Transfer 32
  36. 36. RESTMetadata • Name-Value Pairs • Resource Metadata Allow: GET, HEAD, OPTIONS • Representation Metadata Content-Type: text/plainREpresentational State Transfer 33
  37. 37. RESTControl Data• Defines purpose of the message GET• Used to parameterize request (e.g. caching) If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMTREpresentational State Transfer 34
  38. 38. RESTMedia Types • Data Format = Media Type • Intention • Automated processing • Rendered / viewed by a user • Both • Composite Media Types • Affects LatencyREpresentational State Transfer 35
  39. 39. RESTConnectors • Client • Server • Cache • Shared (Akamai) • Non-shared (browser) • Resolver (DNS) • Tunnel (SSL)REpresentational State Transfer 36
  40. 40. RESTComponents • Origin Server • Gateway • Proxy • User AgentREpresentational State Transfer 37
  41. 41. REST 2 PracticeREpresentational State Transfer 38
  42. 42. RESTREpresentational State Transfer 39
  43. 43. RESTBooking Lifecycle update cancel Cancelled create confirmed Pending Confirmed "live" rejected Served update Rejected deleteREpresentational State Transfer 40
  44. 44. REST CRUDREpresentational State Transfer 41
  45. 45. REST Create New BookingPOST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true} REpresentational State Transfer 42
  46. 46. REST Create New BookingPOST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true} HTTP/1.1 201 Created Content-Type: application/json Location: http://www.booking-rest.com/bookings/9111 { ... «state»: «PENDING» } REpresentational State Transfer 42
  47. 47. RESTPOST?REpresentational State Transfer 43
  48. 48. RESTPOST? • Server determines resource URI • We are changing server state (POST is not safe!) • Resubmitting may create another booking (POST is non- idempotent!)REpresentational State Transfer 43
  49. 49. REST Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ ... «hotel-id»: «mars:escapism», ...} REpresentational State Transfer 44
  50. 50. REST Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ ... «hotel-id»: «mars:escapism», ...} HTTP/1.1 400 Bad Request Content-Type: application/json { «error»: «WTF is your hotel-id?» } REpresentational State Transfer 44
  51. 51. REST Creation Failure - 400POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ ... «hotel-id»: «mars:escapism», ...} Modify request before resubmitting!!! REpresentational State Transfer 45
  52. 52. REST Creation Failure - 500POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true} HTTP/1.1 500 Internal Server Error Content-Type: application/json { «error»: «donno what went wrong» } REpresentational State Transfer 46
  53. 53. REST Creation Failure - 500POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true} throw new Exception(«donno what went wrong») REpresentational State Transfer 47
  54. 54. RESTCreation Failure - 500 • Forward progress is tricky (booking created or not?) • Retry • Recompute state • Try to be descriptive when returning 500 or avoid if it is possibleREpresentational State Transfer 48
  55. 55. REST Creation Failure - 503POST /bookings HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true} HTTP/1.1 503 Service Unavailable Content-Type: application/json Retry-After: 60 { «error»: «Have a headache right now. Please try again in a minute» } REpresentational State Transfer 49
  56. 56. REST CRUDREpresentational State Transfer 50
  57. 57. RESTReading BookingGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» }REpresentational State Transfer 51
  58. 58. RESTGET? • No side effects (GET is safe!) • Resubmitting will return the same result if resource haven’t changed (GET is idempotent / nullipotent!)REpresentational State Transfer 52
  59. 59. RESTReading Booking (Later)GET /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «SERVED» }REpresentational State Transfer 53
  60. 60. RESTReading Booking - 404GET /bookings/mars HTTP/1.1Host: www.booking-rest.com HTTP/1.1 404 Not FoundREpresentational State Transfer 54
  61. 61. REST CRUDREpresentational State Transfer 55
  62. 62. REST Updating BookingPUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING»} HTTP/1.1 200 OK Content-Type: application/json { ... «state»: «PENDING» } REpresentational State Transfer 56
  63. 63. RESTPUT?REpresentational State Transfer 57
  64. 64. RESTPUT? • Client determines resource URI • We are changing server state (PUT is not safe!) • Resubmitting will result in the same resource state (PUT is idempotent!)REpresentational State Transfer 57
  65. 65. REST Updating Booking - 204PUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING»} HTTP/1.1 204 No Content REpresentational State Transfer 58
  66. 66. RESTPUT: 200 or 204? • 200 more descriptive and confirms server-side state • 204 is more efficientREpresentational State Transfer 59
  67. 67. REST Updating Booking - 409PUT /bookings/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING»} HTTP/1.1 409 Conflict Content-Type: application/json { ... «state»: «SERVED» } REpresentational State Transfer 60
  68. 68. REST PUT or POSTfor Create/Update?REpresentational State Transfer 61
  69. 69. RESTPUT/POST Guidelines • Use POST to create a resource identified by a service-generated URI • Use POST to append a resource to (or to update existing resource in) a collection identified by a service-generated URI • Use PUT to create or update a resource identified by a URI computed by the client sending full content of the specified resourceREpresentational State Transfer 62
  70. 70. REST Partial / Bulk Updates?REpresentational State Transfer 63
  71. 71. RESTPartial Update Strategies1. Encapsulate «partial» into its own sub-resource and invoke PUT on it • ... only if this new resource makes sense to others! Don’t do it just to avoid POST!2. Use POST for resource or sub-resource responding with «303 See Other» pointing to parent resource (Fielding разрешает!)3. Use PATCH (once universally deployed)REpresentational State Transfer 64
  72. 72. REST Partial Update - POSTPOST /bookings/9111/dates HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «from»: «2012-07-22», «to»: «2012-07-29»} HTTP/1.1 303 See Other Location: http://www.booking-rest.com/bookings/9111GET /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json ... REpresentational State Transfer 65
  73. 73. REST Partial Update - PUTPUT /bookings/9111/from HTTP/1.1Host: www.booking-rest.comContent-Type: text/plain2012-07-22 HTTP/1.1 200 OK Content-Type: text/plain 2012-07-22 REpresentational State Transfer 66
  74. 74. RESTBulk Update StrategiesREpresentational State Transfer 67
  75. 75. RESTBulk Update Strategies1. HTTP Pipelining 1. Not well supported :( 2. Innappropriate for non-idempotent methods like POST2. Well, use POST, as «universal» method. Respond with «303 See Other»3. If you need to remove a set of sub-resources and list is not very long, just issue DELETE listing ids in the URLREpresentational State Transfer 67
  76. 76. RESTBulk Update - POSTPOST /bookings/cancelled HTTP/1.1Host: www.booking-rest.comContent-Type: application/json{ «ids»: [«9111», «9112», «9113», «9114»]} HTTP/1.1 303 See Other Location: http://www.booking-rest.com/bookingsREpresentational State Transfer 68
  77. 77. REST CRUDREpresentational State Transfer 69
  78. 78. RESTDELETE Booking - 204DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 204 No ContentREpresentational State Transfer 70
  79. 79. REST DELETE Booking - 200DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», «room-type»: «standard-2x», «breakfast»: true, «state»: «SERVED» } REpresentational State Transfer 71
  80. 80. RESTDELETE Booking - 404DELETE /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 404 Not FoundREpresentational State Transfer 72
  81. 81. RESTDELETE Disallowed - 405DELETE /current-time HTTP/1.1Host: www.time.com HTTP/1.1 405 Method Not Allowed Allow: GETREpresentational State Transfer 73
  82. 82. REST Is it REST API?REpresentational State Transfer 74
  83. 83. REST Is it REST API? NOREpresentational State Transfer 74
  84. 84. REST Richardson Maturity ModelREpresentational State Transfer 75
  85. 85. RESTRMMREpresentational State Transfer 76
  86. 86. REST Level 0 - CreatePOST /bookingService HTTP/1.1Content-Type: application/json{ «create»: { «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», ... }} HTTP/1.1 200 OK Content-Type: application/json { «id»: «9111» } REpresentational State Transfer 77
  87. 87. REST Level 0 - RetrievePOST /bookingService HTTP/1.1Content-Type: application/json{ «retrieve»: { «id»: «9111» }} HTTP/1.1 200 OK Content-Type: application/json { «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», ... } REpresentational State Transfer 78
  88. 88. REST Level 0 - ConfirmPOST /bookingService HTTP/1.1Content-Type: application/json{ «confirm»: { «id»: «9111», «credit-card»: «1111-2222-3333-4444», ... }} HTTP/1.1 200 OK Content-Type: application/json { «id»: «1234» } REpresentational State Transfer 79
  89. 89. RESTLevel 0REpresentational State Transfer 80
  90. 90. RESTLevel 01. Single URI endpoint2. Single HTTP method3. Uses HTTP as transport, not app protocol4. Does not use mechanics of the Web5. Usually based on RPCREpresentational State Transfer 80
  91. 91. RESTLevel 01. Single URI endpoint2. Single HTTP method3. Uses HTTP as transport, not app protocol4. Does not use mechanics of the Web5. Usually based on RPC Flickr SOAP API, Google AdSense APIREpresentational State Transfer 80
  92. 92. REST Level 1 - CreatePOST /booking HTTP/1.1Content-Type: application/json{ «create»: { «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», ... }} HTTP/1.1 200 OK Content-Type: application/json { «id»: «9111» } REpresentational State Transfer 81
  93. 93. REST Level 1 - RetrievePOST /booking HTTP/1.1Content-Type: application/json{ «retrieve»: { «id»: «9111» }} HTTP/1.1 200 OK Content-Type: application/json { «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-22», «to»: «2012-07-29», ... } REpresentational State Transfer 82
  94. 94. REST Level 1 - ConfirmPOST /confirmation HTTP/1.1Content-Type: application/json{ «create»: { «id»: «9111», «credit-card»: «1111-2222-3333-4444», ... }} HTTP/1.1 200 OK Content-Type: application/json { «id»: «1234» } REpresentational State Transfer 83
  95. 95. RESTLevel 1REpresentational State Transfer 84
  96. 96. RESTLevel 11. Multiple resources2. Single HTTP method3. Action in URI or payloadREpresentational State Transfer 84
  97. 97. RESTLevel 11. Multiple resources2. Single HTTP method3. Action in URI or payload Flickr «REST» API, Amazon SimpleDBREpresentational State Transfer 84
  98. 98. RESTLevel 2REpresentational State Transfer 85
  99. 99. RESTLevel 21. Many URIs2. Many verbs3. We’ve designed it already ;)REpresentational State Transfer 85
  100. 100. RESTLevel 21. Many URIs2. Many verbs3. We’ve designed it already ;) Amazon S3 Twitter API Google Calendar APIREpresentational State Transfer 85
  101. 101. RESTLevel 2 APIs HTTP-based Type 1 HTTP-based Type 2 Identification of Resources Yes Yes Manipulation of Resources through Yes Yes Representations Self-Descriptive Messages No Yes HATEOAS No No Examples Twitter API Google Calendar APIREpresentational State Transfer 86
  102. 102. REST Level 3?REpresentational State Transfer 87
  103. 103. REST«If the engine of application state (and hence the API) is not being driven byhypertext, then it cannot be RESTful and cannot be a REST API. Period.» Roy T. Fielding, 2008REpresentational State Transfer 88
  104. 104. REST HATEOASREpresentational State Transfer 89
  105. 105. RESTBrowsing Follow links Change application state Move towards your goalREpresentational State Transfer 90
  106. 106. RESTInteractionGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» }REpresentational State Transfer 91
  107. 107. RESTInteractionGET /bookings/9111 HTTP/1.1Host: www.booking-rest.com HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» } Exchange of resource state, not application stateREpresentational State Transfer 91
  108. 108. RESTResource State1. Information belonging to the resource2. Links to related resources3. Possible transition(s) to a future state(s) of the resource { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» }REpresentational State Transfer 92
  109. 109. RESTDomain Application Protocol Legal interactions between consumer and a set of resources involved in a business process update cancel Cancelled create confirmed Pending Confirmed "live" rejected Served update Rejected deleteREpresentational State Transfer 93
  110. 110. REST HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» }REpresentational State Transfer 94
  111. 111. REST HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true «state»: «PENDING» } What’s next?REpresentational State Transfer 94
  112. 112. RESTURI Templates - Service is bound to honoring these templates forever (and URIs do change!) - You’re exposing too much detail about implementationREpresentational State Transfer 95
  113. 113. REST Single entry- point URI(s)REpresentational State Transfer 96
  114. 114. REST Single entry- point URI(s) http://www.booking-rest.com/bookingsREpresentational State Transfer 96
  115. 115. RESTLoose CouplingUnderstanding of specific URI structure‣ Change URI shapes‣ Relocate resources todifferent servers (partitioning)REpresentational State Transfer 97
  116. 116. RESTLoose Coupling Semantics of a «link»!!!REpresentational State Transfer 98
  117. 117. RESTLoose Coupling Semantics of a «link»!!! «link» = hypermedia controlREpresentational State Transfer 98
  118. 118. RESTHypermedia Control HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING», «confirmation»: «http://www.booking-rest.com/confirmation/9111» }REpresentational State Transfer 99
  119. 119. RESTHypermedia Control { ... «confirmation»: «http://www.booking-rest.com/confirmation/9111», «cancellation»: «http://www.booking-rest.com/cancellation/9111», ... }REpresentational State Transfer 100
  120. 120. RESTHypermedia Control { ... «confirmation»: «http://www.booking-rest.com/confirmation/9111», «cancellation»: «http://www.booking-rest.com/cancellation/9111», ... } Elements have different protocolsemantics, but identical link semanticsREpresentational State Transfer 100
  121. 121. RESTBetter Hyperm Control HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING», «link»: { «rel»: «confirmation» «href»: «http://www.booking-rest.com/confirmation/9111» } }REpresentational State Transfer 101
  122. 122. RESTMedia Type HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING», «link»: { «rel»: «confirmation», «href»: «http://www.booking-rest.com/confirmation/9111» } }REpresentational State Transfer 102
  123. 123. RESTMedia Type HTTP/1.1 200 OK Content-Type: application/json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING», «link»: { «rel»: «confirmation», «href»: «http://www.booking-rest.com/confirmation/9111» } } Should it be interpreted as plain vanilla JSON?REpresentational State Transfer 102
  124. 124. REST Content-Type drives processing of the payload, NOT the payload itselfREpresentational State Transfer 103
  125. 125. RESTMedia Type HTTP/1.1 200 OK Content-Type: application/json { «hotel-id»: «paris:bergere-opera-hotel-3», ... «link»: { «rel»: «confirmation», «href»: «http://www.booking-rest.com/confirmation/9111» } } Interpretative scheme for each format includes hypermedia control definitionsREpresentational State Transfer 104
  126. 126. RESTMedia Type HTTP/1.1 200 OK Content-Type: application/json { «hotel-id»: «paris:bergere-opera-hotel-3», ... «link»: { «rel»: «confirmation», «href»: «http://www.booking-rest.com/confirmation/9111» } } Interpretative scheme for each format includes hypermedia control definitions JSON doesn’t define a «link»REpresentational State Transfer 104
  127. 127. RESTBetter Media Type HTTP/1.1 200 OK Content-Type: application/vnd.booking+json { «user-id»: «anonymous-developer», «hotel-id»: «paris:bergere-opera-hotel-3», «from»: «2012-07-20», «to»: «2012-07-27», «room-type»: «standard-2x», «breakfast»: true, «state»: «PENDING», «link»: { «rel»: «confirmation» «href»: «http://www.booking-rest.com/confirmation/9111» } }REpresentational State Transfer 105
  128. 128. REST Should we give each representation a media type?REpresentational State Transfer 106
  129. 129. RESTMedia Types /Representations‣ Usually there is NO 1:1 relationship betweenmedia type and representation‣ Usually having one single monolithic media type istoo bulky‣ One media type per application domain context isusually OKREpresentational State Transfer 107
  130. 130. RESTCreate New Booking HTTP/1.1 201 Created Content-Type: application/vnd.booking+json Location: http://www.booking-rest.com/bookings/9111 { ... «links»: [ { «rel»: «confirm», «href»: «http://www.booking-rest.com/confirmation/9111», «mediaType»: «application/vnd.booking+json» }, { «rel»: «update», «href»: «http://www.booking-rest.com/orders/9111», «mediaType»: «application/vnd.booking+json» }, { «rel»: «cancel», «href»: «http://www.booking-rest.com/confirmation/9111», }, { «rel»: «self», «href»: «http://www.booking-rest.com/orders/9111», «mediaType»: «application/vnd.booking+json» } ] ... }REpresentational State Transfer 108
  131. 131. REST«link»‣ URI - identifies a resource with which theconsumer can interact to progress the applicationprotocol‣ rel - contains semantic markup (=> verb, headers,structure of the payload)‣ [mediaType] - format of the request payloadREpresentational State Transfer 109
  132. 132. REST Confirm BookingPOST /confirmation/9111 HTTP/1.1Host: www.booking-rest.comContent-Type: application/vnd.booking+json{ «card-number»: «1111-2222-3333-4444», «cvc»: «987», «amount»: «1000.00»} HTTP/1.1 200 OK Content-Type: application/vnd.booking+json Location: /confirmation/9111/1234 { ... «links»: [ { «rel»: «receipt», «href»: «http://www.booking-rest.com/confirmation/9111» }, { «rel»: «order», «href»: «http://www.booking-rest.com/orders/9111», } ] ... } REpresentational State Transfer 110
  133. 133. REST «REST doesn’t eliminate the need for aclue. What REST does is concentrate that need for prior knowledge into readilystandardizable forms. That is the essential distinction between data-oriented and control-oriented integration.» Roy T. Fielding, 2008REpresentational State Transfer 111
  134. 134. REST«... It has value because it is far easier tostandardize representation and relation types than it is to standardize objects and object-specific interfaces ...» Roy T. Fielding, 2008REpresentational State Transfer 112
  135. 135. REST VersioningREpresentational State Transfer 113
  136. 136. REST1. Version in URIREpresentational State Transfer 114
  137. 137. REST1. Version in URI http://www.booking-rest.com/v1/bookingsREpresentational State Transfer 114
  138. 138. REST1. Version in URI http://www.booking-rest.com/v1/bookings • /v1/bookings/9111 != /v2/bookings/9111? Not necessarily • Should client support both /v1 and /v2? Maintenance nightmare • Should client start constructing URIs then? Breaks HATEOASREpresentational State Transfer 114
  139. 139. REST2. Version in Media TypeREpresentational State Transfer 115
  140. 140. REST2. Version in Media Type • Another representation of /bookings/9111? Yes! • Should client support both /v1 and /v2? Client chooses which version to support through «Accept» • No need to construct URIs HATEOAS preservedREpresentational State Transfer 115
  141. 141. REST2. Version in Media Type application/vnd.booking.v2+json application/vnd.booking+json; version=2.0 • Another representation of /bookings/9111? Yes! • Should client support both /v1 and /v2? Client chooses which version to support through «Accept» • No need to construct URIs HATEOAS preservedREpresentational State Transfer 115
  142. 142. REST3. Version in HeaderREpresentational State Transfer 116
  143. 143. REST3. Version in Header X-REST-API-Version: 2.0REpresentational State Transfer 116
  144. 144. REST3. Version in Header X-REST-API-Version: 2.0 Also fine but can be filtered out by proxies or intermediariesREpresentational State Transfer 116
  145. 145. REST TransactionsREpresentational State Transfer 117
  146. 146. RESTTransactions1. If you need transactions, treat them as corresponding resources 1. Create transaction as POST 2. Fill it with data and initiate by issuing PUT2. There is no concept of «distributed transaction» in REST. Treat «distributed» nature of the transaction as implementation detailREpresentational State Transfer 118
  147. 147. RESTTransactionPOST /transfer HTTP/1.1Host: www.money-rest.com HTTP/1.1 201 Created Location: http://www.money-rest.com/transfer/9111PUT /transfer/9111 HTTP/1.1Host: www.money-rest.comContent-Type: application/json{ «from»: «husband», «to»: «wife», «amount»: «1000.00», «amount»: «UAH», «description»: «fitness»} HTTP/1.1 204 No ContentREpresentational State Transfer 119
  148. 148. REST Frameworks (Java)REpresentational State Transfer 120
  149. 149. RESTThanks!Questions? 121

×