Pragmatic Rest

Loading...

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

0 comments

Post a comment

    Post a comment
    Embed Video
    Edit your comment Cancel

    6 Favorites

    Pragmatic Rest - Presentation Transcript

    1. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Pragmatic REST Building RESTful Web APIs Subbu Allamaraju Yahoo! Inc || http://subbu.org Subbu Allamaraju – Pragmatic REST
    2. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. About   Tech Yahoo!  Developing standards, patterns and practices for HTTP web APIs   Past  At BEA   A “Convert” Subbu Allamaraju — Pragmatic REST Slide 2
    3. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Disclaimer All the opinions I express here are mine and do not necessarily represent those of my present or past employers. Subbu Allamaraju — Pragmatic REST 3
    4. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Agenda REST – The Architecture REST vs WS – Pros and Cons Building HTTP APIs RESTfully Subbu Allamaraju — Pragmatic REST 4
    5. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Smell Test “We offer SOAP and REST end points” “Our technology supports REST-style URLs” “REST is not fit for machine-machine interactions” Subbu Allamaraju — Pragmatic REST 5
    6. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. QUIZ Subbu Allamaraju — Pragmatic REST 6
    7. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Are these RESTful? http://example.org/persons?start=10&count=100 http://example.org/person/123.xml http://example.org/person/123/address/4 http://example.org/movie/Gone_With_the_Wind http://example.org/movie/Terminator/reviews Subbu Allamaraju — Pragmatic REST Slide 7
    8. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? GET /services/rest/? method=flickr.photos.setPerms&photo_id=2691065403& is_public=1&is_friend=0&is_family=0&perm_comment=1& perm_addmeta=1 HTTP/1.1 Host: example.org HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <rsp stat=\"ok\"> <photoid>2691065403</photoid> </rsp> Subbu Allamaraju — Pragmatic REST Slide 8
    9. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? POST /services/rest/? method=flickr.photos.getRecent&api_key=… HTTP/1.1 Host: example.org HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <rsp stat=\"ok\"> <photos page=\"1\" pages=\"10\" perpage=\"100”> <photo id=\"2947640330\" owner=\"15150729@N07” secret=\"…\" server=\"3060\" farm=\"4\" title=\"…\" ispublic=\"1\" isfriend=\"0\" isfamily=\"0\" /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 9
    10. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? GET /photos?filterBy=recent HTTP/1.1 Host: example.org HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <rsp stat=\"ok\"> <photos page=\"1\" pages=\"10\" perpage=\"100 total=\"1000”> <photo id=\"2947640330\" owner=\"15150729@N07” secret=\"…\" server=\"3060\" farm=\"4\" title=\"…\" ispublic=\"1\" isfriend=\"0\" isfamily=\"0\" /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 10
    11. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? GET /photos?filterBy=recent&api_key=blah Host: example.org 200 OK Content-Type: application/xml;charset=UTF-8 <rsp stat=”fail\"> <err code=\"96\" msg=\"Invalid signature\"/> </rsp> Subbu Allamaraju — Pragmatic REST Slide 11
    12. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. REST Subbu Allamaraju — Pragmatic REST 12
    13. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self- descriptive messages; hypermedia as the engine of application state. - Roy Fielding, 2000 Subbu Allamaraju — Pragmatic REST Slide 13
    14. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. In other words 1.  Resources and URIs 2.  Representations 3.  Uniform interface 4.  HATEOAS Subbu Allamaraju — Pragmatic REST Slide 14
    15. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. But no   Schemas   Description languages   Code generation   Registries Subbu Allamaraju — Pragmatic REST Slide 15
    16. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. REST/HTTP EXPLAINED Subbu Allamaraju — Pragmatic REST 16
    17. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Tenet 1: Resources   A thing with an identity  A blog entry, a person, a friend, an address   Resources are named via URIs  http://example.org/blog/what-is-rest  http://example.org/person/subbu  http://example.org/person/subbu/friends  http://example.org/person/subbu/address/home   URIs are stable  URIs are names  Names don’t change often 17 Subbu Allamaraju — Pragmatic REST
    18. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Identifying Resources   We will come back to this later 18 Subbu Allamaraju — Pragmatic REST
    19. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Assigning URIs Think primary keys A person http://example.org/person/123 An address of a http://example.org/person/123/address/4 person A movie http://example.org/movie/Gone_With_the_Wind Reviews of a http://example.org/movie/Terminator/reviews movie A group of http://example.org/persons?start=10&count=100 people Subbu Allamaraju — Pragmatic REST Slide 19
    20. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. URIS are Generally Opaque Clean URIs don’t generally matter http://example.org/76asfg2g Okay as long as clients don’t have to parse and understand these URI Opacity - We will come back to this later Subbu Allamaraju — Pragmatic REST Slide 20
    21. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. URI Design Considerations Opaque to client apps – Transparent to client developers Hierarchical path segments A good way to organize resources http://example.org/movie/Terminator/ reviews 21 Subbu Allamaraju — Pragmatic REST
    22. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. URI Considerations Reserve query params for optional inputs (A convention, not a rule) http://example.org/movies findBy {latest,director,studio} fromYear Year toYear Year location Postal code, or city … 22 Subbu Allamaraju — Pragmatic REST
    23. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Tenet 2: Representations Things sent over requests and received over responses An XML representation of a book A PNG representation of a map Data submitted through an HTML form to create a user A JSON representation of the user created An HTML view of the same user 23 Subbu Allamaraju — Pragmatic REST
    24. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Media Types Like the “type” of an object Like the “schema” of an XML element An XML representation of a book: application/ vnd.example.book+xml A PNG representation of a map: image/png HTML form submission: application/x-www-form-urlencoded A JSON representation of the user created: application/ vnd.example.user+json An HTML view of the same user: text/html 24 Subbu Allamaraju — Pragmatic REST
    25. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Representations are Negotiable Accept: application/atom+xml;q=1.0,text/html;q=0.1 Accept-Charset: UTF-8 Content-Type: application/atom+xml;charset=UTF-8 Accept-Language: fr;q=1.0,en=0.8 Content-Language: en Accept-Encoding: gzip,deflate Content-Encoding: deflate 25 Subbu Allamaraju — Pragmatic REST
    26. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Varying a Response Don’t overload URIs Tell intermediaries and clients how you chose a representation Accept: application/atom+xml;q=1.0,text/htm;q=0.1 Accept-Charset: UTF-8 Accept-Language: fr;q=1.0,en=0.8 Accept-Encoding: gzip,deflate Content-Type: application/atom+xml;charset=UTF-8 Content-Encoding: deflate Vary: Accept,Accept-Encoding Subbu Allamaraju — Pragmatic REST Slide 26
    27. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Tenet 3 – Uniform Interface Network transparency   A uniform interface to operate on resources   Uniform interface == A fixed set of operations   Uniform interface == Generic interface  Irrespective of what resource is being operated on 27 Subbu Allamaraju — Pragmatic REST
    28. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. HTTP is a Uniform Interface CRUD A protocol between clients and resources GET •  Get a representation •  Safe and idempotent POST •  Like a factory operation •  Unsafe and non-idempotent PUT •  Create or update a resource •  Unsafe but idempotent DELETE •  Delete a resource •  Unsafe but idempotent Subbu Allamaraju — Pragmatic REST Slide 28
    29. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. A Generic Application Protocol   CRUD on resources   Content negotiation   Caching   Optimistic concurrency 29 Subbu Allamaraju — Pragmatic REST
    30. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is CRUD Crude?   Yes, may be – depends on how you identify resources 30 Subbu Allamaraju — Pragmatic REST
    31. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Domain Nouns Obvious Approach   Nouns in your application domain   NYT Movie Reviews API  Movies, Reviews, Critics, Critic’s picks, Reviews by reviewer   Netflix API  Catalog, Users, Rentals, Rental History, Rental Queue, Reviews, Recommendations etc. Subbu Allamaraju — Pragmatic REST Slide 31
    32. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Composites Listen to Client Developers A map with traffic directions + weather alerts + and construction data A user profile with 5 contacts + favorite colors + 10 latest updates   A group of other resources   Generally read-only Subbu Allamaraju — Pragmatic REST Slide 32
    33. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Tasks and Processes Clear the CRUD Transfer $100 from A to B An order processing workflow Hiring an employee   Spawn several resources and have their own lifecycle Subbu Allamaraju — Pragmatic REST Slide 33
    34. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Finding Resources Domain Compo- Nouns sites Tasks & Processes Subbu Allamaraju — Pragmatic REST Slide 34
    35. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. HTTP Caching GET /photo/2691065403/comments 200 OK Last-Modified: Thu, 24 Jul 2008 16:25:14 GMT ETag: 584219-2bb-80758e80 For DB stored data, Cache-Control: max-age=300 maintain version IDs and time stamps GET /photo/2691065403/comments If-Modified-Since: Thu, 24 Jul 2008 16:25:14 GMT If-None-Match: 584219-2bb-80758e80 304 Not Modified Subbu Allamaraju — Pragmatic REST Slide 35
    36. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Optimistic Concurrency GET /photo/2691065403/comment/1 200 OK Last-Modified: Thu, 24 Jul 2008 16:25:14 GMT ETag: 584219-2bb-80758e80 Cache-Control: max-age=300 PUT /photo/2691065403/comment/1 If-Unmodified-Since: Thu, 24 Jul 2008 16:25:14 GMT If-Match: 584219-2bb-80758e80 412 Precondition Failed Subbu Allamaraju — Pragmatic REST Slide 36
    37. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Tenet 4: HATEOAS “Hypermedia as the engine of application state” Subbu Allamaraju — Pragmatic REST Slide 37
    38. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Web APIs without Hypermedia POXy REST   All URIs prepublished   Clients solely rely on documentation   Clients create URIs from scratch   Representations are like POJOs Subbu Allamaraju — Pragmatic REST Slide 38
    39. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Hypermedia for Web APIs <account> <link href=\"http://example.org/transaction/1\" rel=\"self”/> <link href=\"http://example.org/account/1/history\" rel=\"http://example.org/rels/history\"/> <link href=\"http://example.org/customer/aZff13\" rel=\"http://example.org/rels/customer\"/> … </account> http://tools.ietf.org/id/draft-nottingham-http-link- header-02.txt for a consolidated list of well-known relations. Or define your own. Subbu Allamaraju — Pragmatic REST Slide 39
    40. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Hypermedia for Web APIs Representations reflect app state <customer> <link href=\"http://example.org/customer/aZff13\" rel=\"self”/> <link href=\"http://example.org/invite?z09sa3k\" rel=\"http://example.org/rels/verify\"/> … </profile> e.g. a one time link Subbu Allamaraju — Pragmatic REST Slide 40
    41. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. HATEOAS – Consequences   URIs are given to clients  Or clients use known algorithms, or URI templates  Don’t have to prepublish all URIs   URIs can be context and state sensitive   URIs remain opaque  Less coupling Subbu Allamaraju — Pragmatic REST Slide 41
    42. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. URI Templates Use when client needs to supply inputs A URI to fetch all movies with title containing a keyword: http://example.org/movies?contains={keyword} Subbu Allamaraju — Pragmatic REST Slide 42
    43. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Describing Web APIs Hypermedia and media types to reduce the need for description languages such as WADL 43 Subbu Allamaraju — Pragmatic REST
    44. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Describing Web APIs No silver bullet Publish a few root level URIs OPTIONS to discover verbs Media type specifications Links with known relations to discover new contextual URIs Subbu Allamaraju — Pragmatic REST Slide 44
    45. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. EXAMPLE: ACCOUNT TRANSFER Subbu Allamaraju — Pragmatic REST 45
    46. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Account Transfer A client app would like to transfer $100 from one bank account to another. Subbu Allamaraju — Pragmatic REST Slide 46
    47. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Resources and URIs Perhaps upon authentication or through a previous search Bank account: http://example.org/account/{id} Transfers collection: http://example.org/transfers Account transfer: http://example.org/transfer/{id} Status: http://example.org/status/{…} Prepublished, or linked from an account Link returned upon representation account transfer How do client apps find these URIs? Subbu Allamaraju — Pragmatic REST Slide 47
    48. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Representations application/vnd.example.account+xml application/vnd.example.transfer+xml application/vnd.example.status+xml Describe each media type Subbu Allamaraju — Pragmatic REST Slide 48
    49. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Link Relations \"self\": To self-link to each resource \"edit\": Link to create a new transfer request \"http://example.org/rels/source\": Source \"http://example.org/rels/target\": Target \"http://example.org/rels/status\": Status Subbu Allamaraju — Pragmatic REST Slide 49
    50. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Create a Transfer POST /transfers HTTP/1.1 Host: example.org Content-Type: application/vnd.example.transfer+xml <transfer> <link href=\"http://example.org/account/1\" rel=\"http://example.org/rels/source\"/> <link href=\"http://example.org/account/2\" rel=\"http://example.org/rels/target\"/> <currency>USD</currency> <amount>100.00</amount> <note>Testing transfer</note> </transfer> Subbu Allamaraju — Pragmatic REST Slide 50
    51. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Response HTTP/1.1 201 Created Location: http://example.org/transfer/1 Content-Type: application/vnd.example.transfer+xml <transfer> <link href=\"http://example.org/transfer/1\" rel=\"self”/> <link href=\"http://example.org/status/1?z09sa3k\" rel=\"http://example.org/rels/status\"/> <id>org:example:transfer:1</id> … </transfer> Subbu Allamaraju — Pragmatic REST Slide 51
    52. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Get Status GET /status/1?z09sa3k HTTP/1.1 Host: example.org HTTP/1.1 200 OK <status> <link href=\"http://example.org/status/1?z09sa3k\" rel=”self\"/> <id>org:example:status:999</id> <text>…</text> </status> Subbu Allamaraju — Pragmatic REST Slide 52
    53. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. QUIZ - REVISIT Subbu Allamaraju — Pragmatic REST 53
    54. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Are these RESTful? http://example.org/persons?start=10&count=100 http://example.org/person/123.xml http://example.org/person/123/address/4 http://example.org/movie/Gone_With_the_Wind http://example.org/movie/Terminator/reviews There is nothing RESTful or unRESTful. These are just names of resources. Subbu Allamaraju — Pragmatic REST Slide 54
    55. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? GET /services/rest/? method=flickr.photos.setPerms&photo_id=2691065403& is_public=1&is_friend=0&is_family=0&perm_comment=1& perm_addmeta=1 HTTP/1.1 Host: example.org Using an unsafe operation over GET HTTP/1.1 200 OK Use PUT Content-Type: text/xml; charset=utf-8 <rsp stat=\"ok\"> <photoid>2691065403</photoid> </rsp> Subbu Allamaraju — Pragmatic REST Slide 55
    56. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? POST /services/rest/? method=flickr.photos.getRecent&api_key=… HTTP/1.1 Host: example.org Using GET and POST synonymously HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 GET is idempotent and <rsp stat=\"ok\"> not. safe. POST is <photos page=\"1\" pages=\"10\" perpage=\"100”> <photo id=\"2947640330\" owner=\"15150729@N07” secret=\"…\" server=\"3060\" farm=\"4\" title=\"…\" ispublic=\"1\" isfriend=\"0\" isfamily=\"0\" /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 56
    57. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? GET /photos?filterBy=recent HTTP/1.1 Host: example.org HTTP/1.1 200 OK Use links – not internal Content-Type: application/xml;charset-UTF-8 IDs <rsp stat=\"ok\"> <photos page=\"1\" pages=\"10\" perpage=\"100 total=\"1000”> <photo id=\"2947640330\" owner=\"15150729@N07” secret=\"…\" server=\"3060\" farm=\"4\" title=\"…\" ispublic=\"1\" isfriend=\"0\" isfamily=\"0\" /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 57
    58. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Is this RESTful? Hiding errors from GET /photos?filterBy=recent&api_key=blah intermediaries and Host: example.org client infrastructure. Use 4xx or 5xx codes 200 OK Content-Type: application/xml;charset=UTF-8 <rsp stat=”fail\"> <err code=\"96\" msg=\"Invalid signature\"/> </rsp> Subbu Allamaraju — Pragmatic REST Slide 58
    59. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. CHALLENGES Subbu Allamaraju — Pragmatic REST 59
    60. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Key Challenges   Modeling resources  Not just as data, but linked and context aware   Respecting the uniform interface   Programming to hypermedia   And occasional fights between “that one” and “the other one”. Subbu Allamaraju — Pragmatic REST Slide 60
    61. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. THANKS Subbu Allamaraju — Pragmatic REST 61

    + Subbu AllamarajuSubbu Allamaraju, 2 years ago

    custom

    1401 views, 6 favs, 2 embeds more stats

    A session at the Colorado Software Summit 2008 on b more

    More info about this document

    © All Rights Reserved

    Go to text version

    • Total Views 1401
      • 1276 on SlideShare
      • 125 from embeds
    • Comments 0
    • Favorites 6
    • Downloads 0
    Most viewed embeds
    • 92 views on http://www.subbu.org
    • 33 views on http://abrdev.com

    more

    All embeds
    • 92 views on http://www.subbu.org
    • 33 views on http://abrdev.com

    less

    Flagged as inappropriate Flag as inappropriate
    Flag as inappropriate

    Select your reason for flagging this presentation as inappropriate. If needed, use the feedback form to let us know more details.

    Cancel
    File a copyright complaint
    Having problems? Go to our helpdesk?

    Categories