RESTful API design principle webinar by apigee. Check out our blog for the recording and video, thanks!

1. Pragma&c REST
Beware of Dogma
Marsh Gardiner
@earth2marsh
Brian Mulloy
@landlessness
Apigee
@apigee

2. #apidesign
2

3. 3

4. What is Pragma&c REST?

5. What is Pragma&c REST?
• Not strict REST

6. What is Pragma&c REST?
• Not strict REST
• Adoption-centered design

9. Why REST is winning:

10. Why REST is winning:
http://api.twitter.com/1/statuses/public_timeline.json

11. POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
</soap:Header>
<soap:Body>
<m:GetStockPrice xmlns:m="http://www.example.org/stock">
<m:StockName>IBM</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>

13. URLs and Verbs

14. URLs and Verbs
• URL is the LCD

15. URLs and Verbs
• URL is the LCD
• Verbs map to CRUD

17. Good Architecture ! Good Design

18. “ As the flexibility of a system increases, its usability
decreases.
Flexibility‐Usability Tradeoff
Universal Principles of Design

19. “ Successful products typically follow four stages of creaEon:
requirements, design, development, and tes&ng.
Development Cycle
Universal Principles of Design

20. We only need two URLs.

21. The first is for a collecEon.

22. /dogs

23. The second is for an element.

24. /dogs/1234

25. POST
GET
PUT
DELETE

26. CREATE
READ
UPDATE
DELETE

27. Resource POST GET PUT DELETE
create read update delete
create a new bulk update delete all
/dogs list dogs
dog dogs dogs
if exists
update Bo
/dogs/bo error show Bo delete Bo
if not
error
Wikipedia

28. Verbs are bad.

29. Nouns are good.

30. Plurals are beNer.

31. What about associaEons?

32. GET /owners/9876/dogs
POST /owners/9876/dogs

33. What about complex variaEons?

34. Cody Simms

35. Sweep variaEons under the ‘?’

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

37. What about paginaEon?

38. Facebook
offset
limit
TwiNer
page
rpp
LinkedIn
start
count

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

40. What about versioning?

41. earth2marsh

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

43. /v1/dogs

44. Please give me exactly what I need.

45. LinkedIn
/people:(id,first-name,last-name,industry)
Facebook
/joe.smith/friends?fields=id,name,picture
Google (parEal response)
?fields=title,media:group(media:thumbnail)

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

47. What about formats?

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

49. “ The Eme it takes to make a decision increases as the
number of alternaEves increases.
Hick’s Law
Universal Principles of Design

50. /dogs.json
/dogs/bo.json

51. What about searching?

52. Global
/search?q=fluffy+dog
Scoped
/owners/bob/dogs/search?q=fluffy
FormaNed
/search.xml?q=fluffy

53. What about errors?

54. earth2marsh

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

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

57. What about the rest of the URL?

58. Facebook graph.facebook.com
api.facebook.com
developers.facebook.com
Foursquare api.foursquare.com
developers.foursquare.com
TwiNer api.twitter.com
search.twitter.com
stream.twitter.com
dev.twitter.com

59. API gateway
api.teachdogrest.com
Developer connecEon
developers.teachdogrest.com
Do web redirects
api → developers (if from browser)
dev → developers
developer → developers

60. What about defaults?

61. Format
json
PaginaEon (depends on data size)
limit=10&offset=0

62. What about excepEonal stuff?

63. MiguelVieira

64. Client intercepts HTTP error codes

65. TwiNer
/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 excepEonal clients
Add virtualizaEon layer

73. THANK YOU
Ques%ons and ideas to:
#apidesign
Marsh Gardiner Brian Mulloy
@earth2marsh @landlessness
marsh@apigee.com brian@apigee.com