Slides for Tom Marrs BJUG talk on 2/12/2013. See http://boulderjug.org/2013/01/tuesday-february-12-2013-a-night-with-tom-marrs-covering-json-and-rest.html

1. RESTful Design at
Work
Tom Marrs
Architect

2. Your Profile
How?
What?
Where?

3. What’s The Point?
Interface
Design
Matters

4. Our Agenda
RESTful Web Well-
RESTful Web RESTful
Service Designed
Service API
Design RESTful
Best Practices Sources
Guidelines APIs

5. We’re Not Covering
:(-
Security
Lots of Code
SOA
Design Patterns

6. RESTful Design Best
Practices - Roadmap

7. Determine Data Set
Business Context
Requirements
Models

8. Our Case Study -
Mentoring Program
A Relationship
6 meetings
Face-to-face or Phone
Mentoring Checklist

9. Mentoring Program -
User Stories

10. Discover Resources
Type Example
Things Order, Member, Product
Associations Enrollment, Membership, Marriage, Employment
Processes Onboarding, Underwriting, Mentoring
Functions Driving Directions, Search

11. Design Resources

12. Uniform Interface -
HTTP Methods/Verbs
HTTP Verb/
Action
Method
GET Read
POST Create [Update]
PUT Update [Create]
DELETE Delete

13. HTTP Status Codes -
Typical
HTTP Verb/ HTTP Status
Meaning
Method Code
GET 200 OK
GET 404 Not Found
POST 201 Created
PUT 200 OK
PUT 404 Not Found
PUT 409 Conflict
DELETE 200 OK
DELETE 404 Not Found
DELETE 409 Conflict

14. HTTP Status Codes -
Other
HTTP
HTTP Verb/
Status Meaning
Method
Code
POST / PUT / DELETE 202 Accepted - Process request later
POST / PUT / DELETE 204 No Content
GET / PUT / DELETE 301 Moved Permanently
ALL 400 Bad Request
ALL 401 Unauthorized
ALL 500 Internal Server Error

15. Design URIs

16. Of Nouns and Verbs
Nouns - Good
Verbs - Bad

17. Verbs - Really Bad!
/listPairs
/reviewPairStatus
/deletePair
/updateProgress
...
/getAvgWaitTimeForMember - Really??
/provideMemberFeedback
/provideMentorFeedback

18. Of Nouns and
Verbs ... Cont’d

19. Use Parameters -
Simplify Associations
Before (Update Progress)
/pairs/{pairId}/mentor/{mentorId}
After (Update Progress)
/pairs/{pairId}?mentor={mentorId}

20. Pagination
API Pagination Params
Facebook ?offset=100&limit=25
Twitter ?page=5&rpp=25
LinkedIn ?start=100&count=25
Recommended /members?offset=100&limit=25

21. Searching
Global
/search?q=Fred+Smith
Scoped
/search/mentors/32/feedback/q?=leader

22. Versioning
API Sample URI
Twilio /2012-07-11/Accounts/{AccountSid}
SalesForce.com /services/data/v20.0/sobjects/
Account
Facebook ?v=1.0
Recommended /v2/members

23. Versioning ... Cont’d
Change Don’t Change
Deleted / Renamed Resources New Resources
New HTTP Methods
Removed HTTP Methods
Different Data (same URI) New Data Formats
New Attributes / Data Elements

24. Content Negotiation
Format HTTP Request
Accept Header - application/json
JSON
simplytoast.api/members/243.json
Accept Header - application/xml
XML
simplytoast.api/members/243.xml

25. Error Handling
HTTP Status Codes
Error Messages?

26. Error Messages?
Why or Why Not?
{
"status" : {
"user" : {
"message" : "Member Fred Smith already exists."
},
"dev" : {
"code" : 409,
"message" : "Member exists. Only a DELETE or UPDATE is
possible at this point."
}
}
}

27. JSON Object Design
- JSONPad

28. How to Spot a Hybrid

29. Reddit

30. Flickr

31. Flickr API Call
http://api.flickr.com/services/rest/?
method=flickr.cameras.getBrandModels&brand=canon&format=json&noj
soncallback=1

32. Delicious

33. RESTful Web Service
Design Guidelines
Alfresco
Apigee
Atlassian

34. Alfresco

35. Apigee

36. Atlassian

37. Well-Designed
RESTful APIs
Twitter
LinkedIn
Open Library
Twilio

38. LinkedIn - People

39. Twilio - Send SMS

40. REST API Sources -
ProgrammableWeb

41. REST API Sources -
ProgrammableWeb

42. REST API Sources -
BART API Docs

43. REST API Sources -
BART ETA API

44. REST API Sources -
BART-RESTClient

45. Other RESTful APIs
Groupon
GitHub

46. Roll Your Own
RESTful API - Dyson

47. Our Agenda
RESTful Web Well-
RESTful Web RESTful
Service Designed
Service API
Design RESTful
Best Practices Sources
Guidelines APIs

48. What’s The Point?
Interface
Design
Matters

49. Questions?
Tom Marrs
Architect
thomasamarrs@comcast.net
http://www.linkedin.com/in/
TomMarrs
Twitter: @TomMarrs
Skype: t.marrs

50. RESTful API
Resources
Teach a Dog to REST - http://blog.apigee.com/detail/restful_api_design/
Apigee API Best Practices - http://blog.apigee.com/taglist/restful
rapi_doc - http://blogs.burnsidedigital.com/2011/12/generating-api-
documentation-with-rapi_doc/
RESTdoclet - https://github.com/IG-Group/RESTdoclet
API Evangelist - http://apievangelist.com/
The Programmable Web (API Directory) - http://
www.programmableweb.com/apis
Stormpath - http://www.stormpath.com/blog/designing-rest-json-apis

51. RESTful Groups
API Craft - http://groups.google.com/group/api-craft/topics
REST Discuss - http://tech.groups.yahoo.com/group/rest-discuss/

52. REST in Practice

53. RESTful Web
Services

54. RESTful Web
Services Cookbook

55. REST API Design
Handbook

56. RESTful Java with
JAX-RS

57. REST API Design
Rulebook