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. groups.google.com/group/api-craft

3. youtube.com/apigee

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

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

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

30. POST
GET
PUT
DELETE

31. CREATE
READ
UPDATE
DELETE

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.

37. Plurals or singulars?

38. Foursquare
/checkins
GroupOn
/deals
Zappos
/Product

39. Plurals are better.
/dogs

40. Abstract or concrete naming?

41. Super High
/things
High
/animals
Medium
/dogs
Low
/beagles

42. Concrete is better than abstract.
/dogs

43. What about associations?

44. GET /owners/5678/dogs
POST /owners/5678/dogs

45. What about complex variations?

46. Cody Simms

47. Sweep variations under the ‘?’

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

49. Hopkinsii

50. /dogs

51. What about errors?

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

55. What about versioning?

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.

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

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

61. What about pagination?

62. Facebook
offset
limit
Twitter
page
rpp
LinkedIn
start
count

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

64. What about formats?

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

66. /dogs.json
/dogs/1234.json

67. What about defaults?

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?

74. Calculate
Translate
Convert

75. Use verbs not nouns
/convert?from=EUR&to=CNY&amount=100

76. What about searching?

77. Global
/search?q=fluffy+fur
Scoped
/owners/5678/dogs/search?q=fluffy+fur
Formatted
/search.xml?q=fluffy+fur

78. What about counts?

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

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

89. What about authentication?

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
brian@apigee.com