RESTful API Design, Second Edition
•
661 likes•180,325 views
This document provides guidance on designing RESTful APIs. It recommends using nouns instead of verbs, keeping URLs simple with only two endpoints per resource, and following conventions from leading APIs. Complex variations and optional parameters should be "swept behind the '?'." The document emphasizes designing for application developers by making APIs intuitive, consistent and complete while also accommodating exceptional clients. It suggests adding an API virtualization layer to handle complexity.
RESTful API Design, Second Edition
- 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
- 4. To be a RESTafarian or a Pragmatist?
- 6. App App App World of API Internal App API User Store Developer APIs Team Systems
- 7. Application developers are raison d'être for APIs.
- 8. Be pragmatic. For the benefit of application developers.
- 9. Pragmatic RESTful APIs are a design problem.
- 10. baddesigns.com
- 13. Paul Mijksenaar Design for Function Award 2011
- 15. Let’s look at puppies.
- 16. hackett hackett hackett hackett
- 19. A puppy’s world is big.
- 20. JnL law_keven Smithsonian's National Zoo hackett
- 21. ... ... /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 ... ...
- 22. We are on a slippery slope.
- 23. Keep the simple things simple.
- 24. Hopkinsii
- 25. We only need two base URLs per resource.
- 26. The first is for a collection.
- 27. /dogs
- 28. The second is for an element.
- 29. /dogs/1234
- 32. 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
- 33. 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
- 34. 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
- 35. Verbs are bad.
- 36. Nouns are good.
- 40. Abstract or concrete naming?
- 42. Concrete is better than abstract. /dogs
- 45. What about complex variations?
- 46. Cody Simms
- 47. Sweep variations under the ‘?’
- 49. Hopkinsii
- 50. /dogs
- 52. meredithfarmer
- 53. 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"}
- 54. 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”}
- 56. Twilio /2010-04-01/Accounts/ salesforce.com /services/data/v20.0/sobjects/Account Facebook ?v=1.0
- 57. /v1/dogs
- 58. Please give me exactly what I need.
- 65. Google Data ?alt=json Foursquare /venue.json Digg* Accept: application/json ?type=json * The type argument, if present, overrides the Accept header.
- 68. Format json Pagination (depends on data size) limit=10&offset=0
- 69. What about attribute names?
- 70. Twitter "created_at": "Thu Nov 03 05:19:38 +0000 2011" Bing "DateTime": "2011-10-29T09:35:00Z" Foursquare "createdAt": 1320296464
- 71. JSON is for JavaScript Objects var myObject = JSON.parse(response); These looks funny in JavaScript timing = myObject.created_at; timing = myObject.DateTime;
- 72. JavaScript Convention "createdAt": 1320296464 timing = myObject.createdAt; Medial Capitalization aka CamelCase
- 73. What about non-resource-y stuff?
- 75. Use verbs not nouns /convert?from=EUR&to=CNY&amount=100
- 79. /dogs/count
- 80. What about the rest of the URL?
- 81. 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
- 82. API gateway api.teachdogrest.com Developer connection developers.teachdogrest.com Do web redirects api ! developers (if from browser) dev ! developers developer ! developers
- 83. What about exceptional stuff?
- 84. Client intercepts HTTP error codes
- 85. Twitter /public_timelines.json? suppress_response_codes=true HTTP Status Code: 200 {"error" : "Could not authenticate you." }
- 86. 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}
- 87. Client supports limited HTTP methods
- 90. PayPal Permissions Service API Facebook OAuth 2.0 Twitter OAuth 1.0a
- 91. Use latest and greatest OAuth OAuth 2.0 Don’t do something close, but different.
- 92. How do application developers use the API?
- 93. What about chatty applications?
- 94. First be complete & RESTful. Then provide shortcuts.
- 95. Partial response syntax can help. /owners/5678?fields=name,dogs(name)
- 96. What about when building an UI requires a lot of domain knowledge?
- 98. Complement your API with code libraries and SDK.
- 99. Really? All of this? And iterate it?
- 101. Application API Virtualization Layer API API API
- 102. 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
- 103. Questions?
- 104. THANK YOU Subscribe to API webinars at: youtube.com/apigee
- 105. THANK YOU Questions and ideas to: groups.google.com/group/api-craft
- 106. THANK YOU Contact me at: @landlessness [email protected]