Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Teach a Dog to RESTBrian Mulloy@landlessnessApigee@apigee
Application developers are kingmakers.
Make your API easy to learn.
Good APIs are a design problem.
Idempotent methods
I won’t say things like that.
Let’s look at puppies.
hackett   hacketthackett   hackett
.../getAllDogs/locationVerify/foodNeeded/createRecurringDogWalk/giveDirectOrder/healthCheck/getRecurringDogWalkSchedule/ge...
A puppy’s world is big.
JnL               law_kevenSmithsonians National Zoo    hackett
...                                  .../getAllDogs                          /getAllLeashedDogs/verifyLocation            ...
We are on a slippery slope.
Keep the simple things simple.
Hopkinsii
We only need two URLs.
The first is for a collection.
/dogs
The second is for an element.
/dogs/bo
POSTGETPUTDELETE
CREATEREADUPDATEDELETE
Resource     POST            GET        PUT        DELETE             create          read      update      delete        ...
Resource     POST            GET        PUT       DELETE             create          read      update      delete         ...
Resource     POST              GET        PUT        DELETE             create            read      update      delete    ...
Verbs are bad.
Nouns are good.
Plurals are better.
What about associations?
GET /owners/obama/dogsPOST /owners/obama/dogs
What about complex variations?
Cody Simms
Sweep variations under the ‘?’.
/dogs?color=red&state=running&location=park
What about pagination?
FacebookoffsetlimitTwitterpagerppLinkedInstartcount
/dogs?limit=25&offset=50
What about versioning?
Twilio/2010-04-01/Accounts/salesforce.com/services/data/v20.0/sobjects/AccountFacebook?v=1.0
/v1/dogs
Please give me exactly what I need.
LinkedIn/people:(id,first-name,last-name,industry)Facebook/joe.smith/friends?fields=id,name,pictureGoogle (partial respons...
/dogs?fields=name,color,location
What about formats?
Google Data?alt=jsonFoursquare/venue.jsonDiggContent-Type: application/json?type=json
/dogs.json/dogs/bo.json
What about the rest of the URL?
Facebook    graph.facebook.com             api.facebook.com             developers.facebook.comFoursquare   api.foursquare...
API gatewayapi.teachdogrest.comDeveloper connectiondev.teachdogrest.comDo web redirectsapi ! devdevelopers ! devdeveloper ...
Be RESTfulOnly 2 URLsNo verbsUse nouns as pluralsSweep complexity behind the ‘?’Borrow from leading APIs
THANK YOUQuestions and ideas to:Brian Mulloy@landlessnessbrian@apigee.com
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Teach a Dog to REST
Upcoming SlideShare
Loading in …5
×

Teach a Dog to REST

202,905 views

Published on

this is an old version. new version here: http://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_webinar/

It's been 10 years since Fielding first defined REST. So, where are all the elegant REST APIs? While many claim REST has arrived, many APIs in the wild exhibit arbitrary, productivity-killing deviations from true REST. We'll start with a typical poorly-designed API and iterate it into a well-behaved RESTful API.

Teach a Dog to REST

  1. 1. Teach a Dog to RESTBrian Mulloy@landlessnessApigee@apigee
  2. 2. Application developers are kingmakers.
  3. 3. Make your API easy to learn.
  4. 4. Good APIs are a design problem.
  5. 5. Idempotent methods
  6. 6. I won’t say things like that.
  7. 7. Let’s look at puppies.
  8. 8. hackett hacketthackett hackett
  9. 9. .../getAllDogs/locationVerify/foodNeeded/createRecurringDogWalk/giveDirectOrder/healthCheck/getRecurringDogWalkSchedule/getLocation/getDog/massDogParty/getNewDogsSince/getRedDogs/getSittingDogs/dogStateChangesSearch/replaceSittingDogsWithRunningDogs/saveDog...
  10. 10. A puppy’s world is big.
  11. 11. JnL law_kevenSmithsonians National Zoo hackett
  12. 12. ... .../getAllDogs /getAllLeashedDogs/verifyLocation /verifyVeterinarianLocation/feedNeeded /feedNeededFood/createRecurringWakeUp /createRecurringMedication/giveDirectOrder /doDirectOwnerDiscipline/checkHealth /doExpressCheckupWithVeterinarian/getRecurringWakeUpSchedule /getRecurringFeedingSchedule/getLocation /getHungerLevel/getDog /getSquirrelChasingPuppies/newDog /newDogForOwner/getNewDogsSince /getNewDogsAtKennelSince/getRedDogs /getRedDogsWithoutSiblings/getSittingDogs /getSittingDogsAtPark/setDogStateTo /setLeashedDogStateTo/replaceSittingDogsWithRunningDogs /replaceParkSittingDogsWithRunningDogs/saveDog /saveMommaDogsPuppies... ...
  13. 13. We are on a slippery slope.
  14. 14. Keep the simple things simple.
  15. 15. Hopkinsii
  16. 16. We only need two URLs.
  17. 17. The first is for a collection.
  18. 18. /dogs
  19. 19. The second is for an element.
  20. 20. /dogs/bo
  21. 21. POSTGETPUTDELETE
  22. 22. CREATEREADUPDATEDELETE
  23. 23. 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/bo show Bo delete Bo create new if not dog in it create Bo Wikipedia
  24. 24. 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/bo create show Bo delete Bo new dog if not in it create Bo Wikipedia
  25. 25. 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/bo error show Bo delete Bo if not error Wikipedia
  26. 26. Verbs are bad.
  27. 27. Nouns are good.
  28. 28. Plurals are better.
  29. 29. What about associations?
  30. 30. GET /owners/obama/dogsPOST /owners/obama/dogs
  31. 31. What about complex variations?
  32. 32. Cody Simms
  33. 33. Sweep variations under the ‘?’.
  34. 34. /dogs?color=red&state=running&location=park
  35. 35. What about pagination?
  36. 36. FacebookoffsetlimitTwitterpagerppLinkedInstartcount
  37. 37. /dogs?limit=25&offset=50
  38. 38. What about versioning?
  39. 39. Twilio/2010-04-01/Accounts/salesforce.com/services/data/v20.0/sobjects/AccountFacebook?v=1.0
  40. 40. /v1/dogs
  41. 41. Please give me exactly what I need.
  42. 42. LinkedIn/people:(id,first-name,last-name,industry)Facebook/joe.smith/friends?fields=id,name,pictureGoogle (partial response)?fields=title,media:group(media:thumbnail)
  43. 43. /dogs?fields=name,color,location
  44. 44. What about formats?
  45. 45. Google Data?alt=jsonFoursquare/venue.jsonDiggContent-Type: application/json?type=json
  46. 46. /dogs.json/dogs/bo.json
  47. 47. What about the rest of the URL?
  48. 48. Facebook graph.facebook.com api.facebook.com developers.facebook.comFoursquare api.foursquare.com developers.foursquare.com Twitter api.twitter.com search.twitter.com stream.twitter.com dev.twitter.com
  49. 49. API gatewayapi.teachdogrest.comDeveloper connectiondev.teachdogrest.comDo web redirectsapi ! devdevelopers ! devdeveloper ! dev
  50. 50. Be RESTfulOnly 2 URLsNo verbsUse nouns as pluralsSweep complexity behind the ‘?’Borrow from leading APIs
  51. 51. THANK YOUQuestions and ideas to:Brian Mulloy@landlessnessbrian@apigee.com

×