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

2,535

Published on

Published in: Technology, Business
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,535
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
0
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Transcript of "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

    ×