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.

1. Teach a Dog to REST
Brian Mulloy
@landlessness
Apigee
@apigee

2. 20%

3. Application developers are kingmakers.

4. Make your API easy to learn.

5. Good APIs are a design problem.

8. Idempotent methods

9. I won’t say things like that.

10. Let’s look at puppies.

11. hackett hackett
hackett hackett

12. ...
/getAllDogs
/locationVerify
/foodNeeded
/createRecurringDogWalk
/giveDirectOrder
/healthCheck
/getRecurringDogWalkSchedule
/getLocation
/getDog
/massDogParty
/getNewDogsSince
/getRedDogs
/getSittingDogs
/dogStateChangesSearch
/replaceSittingDogsWithRunningDogs
/saveDog
...

14. A puppy’s world is big.

15. JnL law_keven
Smithsonian's National Zoo hackett

16. ... ...
/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
... ...

17. We are on a slippery slope.

18. Keep the simple things simple.

19. Hopkinsii

20. We only need two URLs.

21. The first is for a collection.

22. /dogs

23. The second is for an element.

24. /dogs/bo

25. POST
GET
PUT
DELETE

26. CREATE
READ
UPDATE
DELETE

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/bo show Bo delete Bo
create new
if not
dog in it
create Bo
Wikipedia

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/bo create show Bo delete Bo
new dog if not
in it create Bo
Wikipedia

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/bo error show Bo delete Bo
if not
error
Wikipedia

30. Verbs are bad.

31. Nouns are good.

32. Plurals are better.

33. What about associations?

34. GET /owners/bob/dogs
POST /owners/bob/dogs

35. What about complex variations?

36. Cody Simms

37. Sweep variations under the ‘?’

38. /dogs?color=red&state=running&location=park

39. What about pagination?

40. Facebook
offset
limit
Twitter
page
rpp
LinkedIn
start
count

41. /dogs?limit=25&offset=50

42. What about searching?

43. Global
/search?q=fluffy+dog
Scoped
/owners/bob/dogs/search?q=fluffy

44. What about versioning?

45. Twilio
/2010-04-01/Accounts/
salesforce.com
/services/data/v20.0/sobjects/Account
Facebook
?v=1.0

46. /v1/dogs

47. Please give me exactly what I need.

48. 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)

49. /dogs?fields=name,color,location

50. What about formats?

51. Google Data
?alt=json
Foursquare
/venue.json
Digg*
Accept: application/json
?type=json
* The type argument, if present, overrides the Accept header.

52. /dogs.json
/dogs/bo.json

53. What about partial updates?

54. What about errors?

55. meredithfarmer

56. 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"}

57. 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”}

58. What about the rest of the URL?

59. 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

60. API gateway
api.teachdogrest.com
Developer connection
dev.teachdogrest.com
Do web redirects
api ! dev
developers ! dev
developer ! dev

61. What about defaults?

62. Format
json
Pagination (depends on data size)
limit=10&offset=0

63. What about exceptional stuff?

64. Client intercepts HTTP error codes

65. Twitter
/public_timelines.json?
suppress_response_codes=true
HTTP Status Code: 200
{"error" : "Could not authenticate
you." }

66. 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}

67. Client supports limited HTTP methods

68. Method Parameter
create
/dogs?method=post
read
/dogs
update
/dogs/bo?method=put&location=park
delete
/dogs/bo?method=delete

69. Really? All of this? And iterate it?

71. Application
API Virtualization Layer
API API API

72. Be RESTful
Only 2 URLs
No verbs
Use nouns as plurals
Sweep complexity behind the ‘?’
Borrow from leading APIs
Account for exceptional clients
Add virtualization layer

73. THANK YOU
Questions and ideas to:
Brian Mulloy
@landlessness
brian@apigee.com