Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




              Pragmatic REST
         ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                About
   Tech Yahoo!
...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Disclaimer



  All th...
Colorado Software Summit: October 19 – 24, 2008           © Copyright 2008, Yahoo! Inc.




                Agenda

      ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Smell Test

       “We...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       QUIZ




Subbu Allamaraju — Pra...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Are these RESTful?
   ...
Colorado Software Summit: October 19 – 24, 2008     © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
   ...
Colorado Software Summit: October 19 – 24, 2008     © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
   ...
Colorado Software Summit: October 19 – 24, 2008     © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
   ...
Colorado Software Summit: October 19 – 24, 2008    © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
    ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       REST




Subbu Allamaraju — Pra...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




 REST is defined by four interface con...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                In other words
 1.  Re...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                But no
   Schemas
  ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       REST/HTTP EXPLAINED




Subbu A...
Colorado Software Summit: October 19 – 24, 2008       © Copyright 2008, Yahoo! Inc.




                Tenet 1: Resources...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Identifying Resources
...
Colorado Software Summit: October 19 – 24, 2008                         © Copyright 2008, Yahoo! Inc.




                ...
Colorado Software Summit: October 19 – 24, 2008                    © Copyright 2008, Yahoo! Inc.




                URIS ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                URI Design Considerati...
Colorado Software Summit: October 19 – 24, 2008                                 © Copyright 2008, Yahoo! Inc.




        ...
Colorado Software Summit: October 19 – 24, 2008                       © Copyright 2008, Yahoo! Inc.




                Te...
Colorado Software Summit: October 19 – 24, 2008                   © Copyright 2008, Yahoo! Inc.




                Media ...
Colorado Software Summit: October 19 – 24, 2008             © Copyright 2008, Yahoo! Inc.




                Representati...
Colorado Software Summit: October 19 – 24, 2008             © Copyright 2008, Yahoo! Inc.




                Varying a Re...
Colorado Software Summit: October 19 – 24, 2008               © Copyright 2008, Yahoo! Inc.




                Tenet 3 – ...
Colorado Software Summit: October 19 – 24, 2008                                    © Copyright 2008, Yahoo! Inc.




     ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                A Generic Application ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Is CRUD Crude?
   Yes...
Colorado Software Summit: October 19 – 24, 2008           © Copyright 2008, Yahoo! Inc.




                Domain Nouns
 ...
Colorado Software Summit: October 19 – 24, 2008                     © Copyright 2008, Yahoo! Inc.




                Comp...
Colorado Software Summit: October 19 – 24, 2008                        © Copyright 2008, Yahoo! Inc.




                T...
Colorado Software Summit: October 19 – 24, 2008                     © Copyright 2008, Yahoo! Inc.




                Find...
Colorado Software Summit: October 19 – 24, 2008                © Copyright 2008, Yahoo! Inc.




                HTTP Cach...
Colorado Software Summit: October 19 – 24, 2008                     © Copyright 2008, Yahoo! Inc.




                Opti...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Tenet 4: HATEOAS




 ...
Colorado Software Summit: October 19 – 24, 2008    © Copyright 2008, Yahoo! Inc.




                Web APIs without Hype...
Colorado Software Summit: October 19 – 24, 2008               © Copyright 2008, Yahoo! Inc.




                Hypermedia...
Colorado Software Summit: October 19 – 24, 2008          © Copyright 2008, Yahoo! Inc.




                Hypermedia for ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                HATEOAS – Consequences...
Colorado Software Summit: October 19 – 24, 2008     © Copyright 2008, Yahoo! Inc.




                URI Templates
      ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Describing Web APIs


...
Colorado Software Summit: October 19 – 24, 2008                        © Copyright 2008, Yahoo! Inc.




                D...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       EXAMPLE: ACCOUNT
       TRANSFE...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Account Transfer



  ...
Colorado Software Summit: October 19 – 24, 2008                         © Copyright 2008, Yahoo! Inc.




                ...
Colorado Software Summit: October 19 – 24, 2008                      © Copyright 2008, Yahoo! Inc.




                Rep...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Link Relations

    qu...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Create a Transfer
  PO...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Response
  HTTP/1.1 20...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Get Status
  GET /stat...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       QUIZ - REVISIT




Subbu Allama...
Colorado Software Summit: October 19 – 24, 2008                              © Copyright 2008, Yahoo! Inc.




           ...
Colorado Software Summit: October 19 – 24, 2008                        © Copyright 2008, Yahoo! Inc.




                I...
Colorado Software Summit: October 19 – 24, 2008     © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
   ...
Colorado Software Summit: October 19 – 24, 2008          © Copyright 2008, Yahoo! Inc.




                Is this RESTful...
Colorado Software Summit: October 19 – 24, 2008    © Copyright 2008, Yahoo! Inc.




                Is this RESTful?
    ...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       CHALLENGES




Subbu Allamaraju...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




                Key Challenges
   Mod...
Colorado Software Summit: October 19 – 24, 2008   © Copyright 2008, Yahoo! Inc.




       THANKS




Subbu Allamaraju — P...
Upcoming SlideShare
Loading in …5
×

Pragmatic Rest

7,423 views

Published on

A session at the Colorado Software Summit 2008 on building HTTP APIs RESTfully

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

No Downloads
Views
Total views
7,423
On SlideShare
0
From Embeds
0
Number of Embeds
745
Actions
Shares
0
Downloads
0
Comments
0
Likes
22
Embeds 0
No embeds

No notes for slide

Pragmatic Rest

  1. 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. 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. 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. 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. 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. 6. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. QUIZ Subbu Allamaraju — Pragmatic REST 6
  7. 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. 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=quot;okquot;> <photoid>2691065403</photoid> </rsp> Subbu Allamaraju — Pragmatic REST Slide 8
  9. 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=quot;okquot;> <photos page=quot;1quot; pages=quot;10quot; perpage=quot;100”> <photo id=quot;2947640330quot; owner=quot;15150729@N07” secret=quot;…quot; server=quot;3060quot; farm=quot;4quot; title=quot;…quot; ispublic=quot;1quot; isfriend=quot;0quot; isfamily=quot;0quot; /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 9
  10. 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=quot;okquot;> <photos page=quot;1quot; pages=quot;10quot; perpage=quot;100 total=quot;1000”> <photo id=quot;2947640330quot; owner=quot;15150729@N07” secret=quot;…quot; server=quot;3060quot; farm=quot;4quot; title=quot;…quot; ispublic=quot;1quot; isfriend=quot;0quot; isfamily=quot;0quot; /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 10
  11. 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=”failquot;> <err code=quot;96quot; msg=quot;Invalid signaturequot;/> </rsp> Subbu Allamaraju — Pragmatic REST Slide 11
  12. 12. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. REST Subbu Allamaraju — Pragmatic REST 12
  13. 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. 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. 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. 16. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. REST/HTTP EXPLAINED Subbu Allamaraju — Pragmatic REST 16
  17. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 39. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Hypermedia for Web APIs <account> <link href=quot;http://example.org/transaction/1quot; rel=quot;self”/> <link href=quot;http://example.org/account/1/historyquot; rel=quot;http://example.org/rels/historyquot;/> <link href=quot;http://example.org/customer/aZff13quot; rel=quot;http://example.org/rels/customerquot;/> … </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. 40. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Hypermedia for Web APIs Representations reflect app state <customer> <link href=quot;http://example.org/customer/aZff13quot; rel=quot;self”/> <link href=quot;http://example.org/invite?z09sa3kquot; rel=quot;http://example.org/rels/verifyquot;/> … </profile> e.g. a one time link Subbu Allamaraju — Pragmatic REST Slide 40
  41. 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. 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. 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. 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. 45. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. EXAMPLE: ACCOUNT TRANSFER Subbu Allamaraju — Pragmatic REST 45
  46. 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. 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. 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. 49. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. Link Relations quot;selfquot;: To self-link to each resource quot;editquot;: Link to create a new transfer request quot;http://example.org/rels/sourcequot;: Source quot;http://example.org/rels/targetquot;: Target quot;http://example.org/rels/statusquot;: Status Subbu Allamaraju — Pragmatic REST Slide 49
  50. 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=quot;http://example.org/account/1quot; rel=quot;http://example.org/rels/sourcequot;/> <link href=quot;http://example.org/account/2quot; rel=quot;http://example.org/rels/targetquot;/> <currency>USD</currency> <amount>100.00</amount> <note>Testing transfer</note> </transfer> Subbu Allamaraju — Pragmatic REST Slide 50
  51. 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=quot;http://example.org/transfer/1quot; rel=quot;self”/> <link href=quot;http://example.org/status/1?z09sa3kquot; rel=quot;http://example.org/rels/statusquot;/> <id>org:example:transfer:1</id> … </transfer> Subbu Allamaraju — Pragmatic REST Slide 51
  52. 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=quot;http://example.org/status/1?z09sa3kquot; rel=”selfquot;/> <id>org:example:status:999</id> <text>…</text> </status> Subbu Allamaraju — Pragmatic REST Slide 52
  53. 53. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. QUIZ - REVISIT Subbu Allamaraju — Pragmatic REST 53
  54. 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. 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=quot;okquot;> <photoid>2691065403</photoid> </rsp> Subbu Allamaraju — Pragmatic REST Slide 55
  56. 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=quot;okquot;> not. safe. POST is <photos page=quot;1quot; pages=quot;10quot; perpage=quot;100”> <photo id=quot;2947640330quot; owner=quot;15150729@N07” secret=quot;…quot; server=quot;3060quot; farm=quot;4quot; title=quot;…quot; ispublic=quot;1quot; isfriend=quot;0quot; isfamily=quot;0quot; /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 56
  57. 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=quot;okquot;> <photos page=quot;1quot; pages=quot;10quot; perpage=quot;100 total=quot;1000”> <photo id=quot;2947640330quot; owner=quot;15150729@N07” secret=quot;…quot; server=quot;3060quot; farm=quot;4quot; title=quot;…quot; ispublic=quot;1quot; isfriend=quot;0quot; isfamily=quot;0quot; /> … </photos> </rsp> Subbu Allamaraju — Pragmatic REST Slide 57
  58. 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=”failquot;> <err code=quot;96quot; msg=quot;Invalid signaturequot;/> </rsp> Subbu Allamaraju — Pragmatic REST Slide 58
  59. 59. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. CHALLENGES Subbu Allamaraju — Pragmatic REST 59
  60. 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. 61. Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc. THANKS Subbu Allamaraju — Pragmatic REST 61

×