Successfully reported this slideshow.
Your SlideShare is downloading. ×

RESTful API Design, Second Edition

Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
RESTful API Design
Second Edition



Brian Mulloy
@landlessness

                 11.03.11 @ 11:03:11 PST
Apigee          ...
groups.google.com/group/api-craft
youtube.com/apigee

YouTube videos are no longer supported on SlideShare

View original on YouTube

Upcoming SlideShare
Teach a Dog to REST
Teach a Dog to REST
Loading in …3
×

Check these out next

1 of 107 Ad
Advertisement

More Related Content

More from Apigee | Google Cloud (20)

Advertisement

RESTful API Design, Second Edition

  1. 1. RESTful API Design Second Edition Brian Mulloy @landlessness 11.03.11 @ 11:03:11 PST Apigee Dial-in or VoIP @apigee See Details in Chat Window
  2. 2. groups.google.com/group/api-craft
  3. 3. youtube.com/apigee
  4. 4. To be a RESTafarian or a Pragmatist?
  5. 5. App App App World of API Internal App API User Store Developer APIs Team Systems
  6. 6. Application developers are raison d'être for APIs.
  7. 7. Be pragmatic. For the benefit of application developers.
  8. 8. Pragmatic RESTful APIs are a design problem.
  9. 9. baddesigns.com
  10. 10. Paul Mijksenaar Design for Function Award 2011
  11. 11. Let’s look at puppies.
  12. 12. hackett hackett hackett hackett
  13. 13. ... /getAllDogs /locationVerify /foodNeeded /createRecurringDogWalk /giveDirectOrder /healthCheck /getRecurringDogWalkSchedule /getLocation /getDog /massDogParty /getNewDogsSince /getRedDogs /getSittingDogs /dogStateChangesSearch /replaceSittingDogsWithRunningDogs /saveDog ...
  14. 14. A puppy’s world is big.
  15. 15. JnL law_keven Smithsonian's National Zoo hackett
  16. 16. ... ... /getAllDogs /getAllLeashedDogs /verifyLocation /verifyVeterinarianLocation /feedNeeded /feedNeededFood /createRecurringWakeUp /createRecurringMedication /giveDirectOrder /doDirectOwnerDiscipline /checkHealth /doExpressCheckupWithVeterinarian /getRecurringWakeUpSchedule /getRecurringFeedingSchedule /getLocation /getHungerLevel /getDog /getSquirrelsChasingPuppies /newDog /newDogForOwner /getNewDogsSince /getNewDogsAtKennelSince /getRedDogs /getRedDogsWithoutSiblings /getSittingDogs /getSittingDogsAtPark /setDogStateTo /setLeashedDogStateTo /replaceSittingDogsWithRunningDogs /replaceParkSittingDogsWithRunningDogs /saveDog /saveMommaDogsPuppies ... ...
  17. 17. We are on a slippery slope.
  18. 18. Keep the simple things simple.
  19. 19. Hopkinsii
  20. 20. We only need two base URLs per resource.
  21. 21. The first is for a collection.
  22. 22. /dogs
  23. 23. The second is for an element.
  24. 24. /dogs/1234
  25. 25. POST GET PUT DELETE
  26. 26. CREATE READ UPDATE DELETE
  27. 27. Resource POST GET PUT DELETE create read update delete replace create a delete all /dogs list dogs dogs with new dog dogs new dogs if exists treat as a update Bo collection /dogs/1234 show Bo delete Bo create new if not dog in it create Bo Wikipedia
  28. 28. Resource POST GET PUT DELETE create read update delete replace create a delete all /dogs list dogs dogs with new dog dogs new dogs treat as a if exists collection update Bo /dogs/1234 create show Bo delete Bo new dog if not in it create Bo Wikipedia
  29. 29. Resource POST GET PUT DELETE create read update delete bulk create a delete all /dogs list dogs update new dog dogs dogs if exists update Bo /dogs/1234 error show Bo delete Bo if not error Wikipedia
  30. 30. Verbs are bad.
  31. 31. Nouns are good.
  32. 32. Plurals or singulars?
  33. 33. Foursquare /checkins GroupOn /deals Zappos /Product
  34. 34. Plurals are better. /dogs
  35. 35. Abstract or concrete naming?
  36. 36. Super High /things High /animals Medium /dogs Low /beagles
  37. 37. Concrete is better than abstract. /dogs
  38. 38. What about associations?
  39. 39. GET /owners/5678/dogs POST /owners/5678/dogs
  40. 40. What about complex variations?
  41. 41. Cody Simms
  42. 42. Sweep variations under the ‘?’
  43. 43. /dogs?color=red&state=running&location=park
  44. 44. Hopkinsii
  45. 45. /dogs
  46. 46. What about errors?
  47. 47. meredithfarmer
  48. 48. Facebook HTTP Status Code: 200 {"type":"OAuthException","message":"(#803) Some of the aliases you requested do not exist: foo.bar"} Twilio HTTP Status Code: 401 {"status":401,"message":"Authenticate","code": 20003,"more_info":"http://www.twilio.com/docs/ errors/20003"} SimpleGeo HTTP Status Code: 401 {"code":401,"message":"Authentication Required"}
  49. 49. Code for code 200 - OK 401 - Unauthorized http://en.wikipedia.org/wiki/List_of_HTTP_status_codes Message for people {“message” : “Verbose, plain language description of the problem with hints about how to fix it.” “more_info” : “http://dev.teachdogrest.com/ errors/12345”}
  50. 50. What about versioning?
  51. 51. Twilio /2010-04-01/Accounts/ salesforce.com /services/data/v20.0/sobjects/Account Facebook ?v=1.0
  52. 52. /v1/dogs
  53. 53. Please give me exactly what I need.
  54. 54. LinkedIn /people:(id,first-name,last-name,industry) Facebook /joe.smith/friends?fields=id,name,picture Google (partial response) ?fields=title,media:group(media:thumbnail)
  55. 55. /dogs?fields=name,color,location
  56. 56. What about pagination?
  57. 57. Facebook offset limit Twitter page rpp LinkedIn start count
  58. 58. /dogs?limit=25&offset=50
  59. 59. What about formats?
  60. 60. Google Data ?alt=json Foursquare /venue.json Digg* Accept: application/json ?type=json * The type argument, if present, overrides the Accept header.
  61. 61. /dogs.json /dogs/1234.json
  62. 62. What about defaults?
  63. 63. Format json Pagination (depends on data size) limit=10&offset=0
  64. 64. What about attribute names?
  65. 65. Twitter "created_at": "Thu Nov 03 05:19:38 +0000 2011" Bing "DateTime": "2011-10-29T09:35:00Z" Foursquare "createdAt": 1320296464
  66. 66. JSON is for JavaScript Objects var myObject = JSON.parse(response); These looks funny in JavaScript timing = myObject.created_at; timing = myObject.DateTime;
  67. 67. JavaScript Convention "createdAt": 1320296464 timing = myObject.createdAt; Medial Capitalization aka CamelCase
  68. 68. What about non-resource-y stuff?
  69. 69. Calculate Translate Convert
  70. 70. Use verbs not nouns /convert?from=EUR&to=CNY&amount=100
  71. 71. What about searching?
  72. 72. Global /search?q=fluffy+fur Scoped /owners/5678/dogs/search?q=fluffy+fur Formatted /search.xml?q=fluffy+fur
  73. 73. What about counts?
  74. 74. /dogs/count
  75. 75. What about the rest of the URL?
  76. 76. Facebook graph.facebook.com api.facebook.com developers.facebook.com Foursquare api.foursquare.com developers.foursquare.com Twitter api.twitter.com search.twitter.com stream.twitter.com dev.twitter.com
  77. 77. API gateway api.teachdogrest.com Developer connection developers.teachdogrest.com Do web redirects api ! developers (if from browser) dev ! developers developer ! developers
  78. 78. What about exceptional stuff?
  79. 79. Client intercepts HTTP error codes
  80. 80. Twitter /public_timelines.json? suppress_response_codes=true HTTP Status Code: 200 {"error" : "Could not authenticate you." }
  81. 81. Always returns OK /dogs?suppress_response_codes=true Code for code ignoring 200 - OK Message for people & code {“response_code” : “401”, “message” : “Verbose, plain language description of the problem with hints about how to fix it.” “more_info” : “http://dev.teachdogrest.com/ errors/12345”, “code” : 12345}
  82. 82. Client supports limited HTTP methods
  83. 83. Method Parameter create /dogs?method=post read /dogs update /dogs/1234?method=put&location=park delete /dogs/1234?method=delete
  84. 84. What about authentication?
  85. 85. PayPal Permissions Service API Facebook OAuth 2.0 Twitter OAuth 1.0a
  86. 86. Use latest and greatest OAuth OAuth 2.0 Don’t do something close, but different.
  87. 87. How do application developers use the API?
  88. 88. What about chatty applications?
  89. 89. First be complete & RESTful. Then provide shortcuts.
  90. 90. Partial response syntax can help. /owners/5678?fields=name,dogs(name)
  91. 91. What about when building an UI requires a lot of domain knowledge?
  92. 92. Complement your API with code libraries and SDK.
  93. 93. Really? All of this? And iterate it?
  94. 94. Application API Virtualization Layer API API API
  95. 95. Be RESTful Only 2 URLs No verbs Use nouns as plurals Concrete over abstract For JSON follow JavaScript conventions Sweep complexity behind the ‘?’ Borrow from leading APIs Account for exceptional clients Add virtualization layer
  96. 96. Questions?
  97. 97. THANK YOU Subscribe to API webinars at: youtube.com/apigee
  98. 98. THANK YOU Questions and ideas to: groups.google.com/group/api-craft
  99. 99. THANK YOU Contact me at: @landlessness brian@apigee.com

×