Tom Marrs: Restful API Design At Work

Tom's Slides from the June 4th, 2013 Denver Open Source Users' Group Meeting: Restful API Design At Work

Transcript

1. RESTful API Design at Work Tom Marrs Architect Friday, May 10, 13
2. Your Profile How? What? Where? Friday, May 10, 13
3. About Me ... Friday, May 10, 13
4. What’s The Point? RESTful API Design Matters Friday, May 10, 13
5. Our Agenda Friday, May 10, 13
6. We’re Not Covering :(- Security Lots of Code SOA Design Patterns Friday, May 10, 13
7. Where Are We? Friday, May 10, 13
8. RESTful Design Best Practices - Roadmap Friday, May 10, 13
9. Determine Data Set Business Context Requirements Models Friday, May 10, 13
10. Our Case Study - Mentoring Program A Relationship 6 meetings Face-to-face or Phone Mentoring Checklist Friday, May 10, 13
11. Mentoring Program - User Stories Friday, May 10, 13
12. Discover Resources Type Example Things Order, Member, Product Associations Enrollment, Membership, Marriage, Employment Processes Onboarding, Underwriting, Mentoring Functions Driving Directions, Search Friday, May 10, 13
13. Design Resources Friday, May 10, 13
14. Uniform Interface - HTTP Methods/Verbs HTTP Verb/ Method Action GET Read POST Create [Update] PUT Update [Create] DELETE Delete Friday, May 10, 13
15. HTTP Status Codes - Typical HTTP Verb/ Method HTTP Status Code Meaning 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 Friday, May 10, 13
16. HTTP Status Codes - Other HTTP Verb/ Method HTTP Status Code Meaning 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 Friday, May 10, 13
17. Design URIs Friday, May 10, 13
18. Of Nouns and Verbs Nouns - Good Verbs - Bad Friday, May 10, 13
19. Verbs - Really Bad! /listPairs /reviewPairStatus /deletePair /updateProgress ... /getAvgWaitTimeForMember - Really?? /provideMemberFeedback /provideMentorFeedback Friday, May 10, 13
20. Our URIs http://mentoring.simplytoast.org/ URI Description Method pairs List all Pairs GET pairs/completed List all Completed Pairs GET pairs/2010/Q4 List all Pairs in Period GET pairs/{pairId} Review Pair Status GET pairs/{pairId} Update Pair Status PUT pairs/{pairId}/mentors/ {mentorId} Update progress PUT Friday, May 10, 13
21. Our URIs ... Cont’d URI Description Method pairs/{pairId} Assign Mentor POST pairs/{pairId} Delete Pair DELETE members List all Members in Program GET members/unassigned List all unassigned Members GET members/avg-wait Get average wait time GET members Add Member (register) POST Friday, May 10, 13
22. Our URIs ... Cont’d URI Description Method members/{memberId} Delete Member DELETE members/{memberId}/ feedback Get Feedback by Member GET members/{memberId}/ feedback Provide Feedback POST mentors List all Mentors GET mentors/available List all available Mentors GET mentors/{mentorId} Update Mentor PUT Friday, May 10, 13
23. Our URIs ... Cont’d URI Description Method mentors Add Mentor (register) POST mentors/{mentorId} Delete Mentor DELETE Friday, May 10, 13
24. Use Parameters - Simplify Associations Before (Update Progress) /pairs/{pairId}/mentor/{mentorId} After (Update Progress) /pairs/{pairId}?mentor={mentorId} Friday, May 10, 13
25. 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 Friday, May 10, 13
26. Searching Global /search?q=Fred+Smith Scoped /search/mentors/32/feedback/q?=leader Friday, May 10, 13
27. 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 Friday, May 10, 13
28. Versioning ... Cont’d Change Don’t Change Deleted / Renamed Resources New Resources Removed HTTP Methods New HTTP Methods Different Data (same URI) New Data Formats New Attributes / Data Elements Friday, May 10, 13
29. Content Negotiation Format HTTP Request JSON Accept Header - application/json simplytoast.api/members/243.json XML Accept Header - application/xml simplytoast.api/members/243.xml Friday, May 10, 13
30. Error Handling HTTP Status Codes Error Messages? Friday, May 10, 13
31. Error Messages? Why or Why Not? Friday, May 10, 13
32. JSON Object Design - JSONPad Friday, May 10, 13
33. How to Spot a Hybrid Friday, May 10, 13
34. Reddit Friday, May 10, 13
35. Flickr Friday, May 10, 13
36. Flickr API Call http://api.flickr.com/services/rest/? method=flickr.cameras.getBrandModels&brand=canon&format=json&noj soncallback=1 Friday, May 10, 13
37. Delicious Friday, May 10, 13
38. Where Are We? Friday, May 10, 13
39. RESTful Web Service Design Guidelines Alfresco Apigee Atlassian Friday, May 10, 13
40. Alfresco Friday, May 10, 13
41. Apigee Friday, May 10, 13
42. Atlassian Friday, May 10, 13
43. Where Are We? Friday, May 10, 13
44. Well-Designed RESTful APIs Twitter LinkedIn Open Library Twilio Friday, May 10, 13
45. LinkedIn - People Friday, May 10, 13
46. Twilio - Send SMS Friday, May 10, 13
47. Other RESTful APIs Groupon GitHub Trello Friday, May 10, 13
48. Trello Friday, May 10, 13
49. Where Are We? Friday, May 10, 13
50. REST API Sources - ProgrammableWeb Friday, May 10, 13
51. API Hub Friday, May 10, 13
52. WebShell Friday, May 10, 13
53. Roll Your Own RESTful API - Dyson Friday, May 10, 13
54. Node.js - Briefly Friday, May 10, 13
55. Dyson Demo dyson init members cd members npm install dyson-image --save-dev npm install dyson-generators --save-dev cd .. (back to projects directory) dyson members http://localhost:3000/members/1 http://localhost:3000/members Friday, May 10, 13
56. Our Agenda Friday, May 10, 13
57. What’s The Point? RESTful API Design Matters Friday, May 10, 13
58. Questions? Tom Marrs Architect thomasamarrs@comcast.net Friday, May 10, 13
59. 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 Friday, May 10, 13
60. RESTful Groups API Craft - http://groups.google.com/group/api-craft/topics REST Discuss - http://tech.groups.yahoo.com/group/rest-discuss/ Friday, May 10, 13
61. REST in Practice Friday, May 10, 13
62. RESTful Web Services Friday, May 10, 13
63. RESTful Web Services Cookbook Friday, May 10, 13
64. REST API Design Handbook Friday, May 10, 13
65. RESTful Java with JAX-RS Friday, May 10, 13
66. REST API Design Rulebook Friday, May 10, 13