Developer Experience: The UX of APIs

SXSW 2013 workshop: http://schedule.sxsw.com/2013/events/event_IAP4740

Workshop website: http://dx.jeremiahlee.com/

Transcript

1. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 Developer Experience: The UX of APIs Jeremiah Lee Cohick, Brian Smith, R. Kevin Nelson, Neil Mansilla 2013-03-11 #DX
2. Over the last few years, we've been studying theprocess designers (and their teams) use to make important decisions like these. In the course of our work, we've discovered there are five common styles of design that almost every team uses: (1) Unintended, (2) Self, (3) Genius, (4) Activity Focused, and (5) Experience Focused. -- User Interface Engineering
3. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 AGENDA 3:30 - Jeremiah Cohick design methodologies conducting user research UX hierarchy of needs design patterns from the real world 4:30 - Break 4:40 - Brian Smith SDK Design 5:10 - Panel Discussion Brian Smith Kevin Nelson Neil Mansilla
4. UX IS EMPATHY AS AN APPLIED SCIENCE
5. SUPPORTING THIRD- PARTY DEVELOPERS TAKES MORE THAN CODE
6. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
7. Over the last few years, we've been studying the process designers (and their teams) use to make important decisions like these. In the course of our work, we've discovered there are five common styles of design that almost every team uses: (1) Unintended, (2) Self, (3) Genius, (4) Activity Focused, and (5) Experience Focused. -- User Interface Engineering
8. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
9. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
10. Unintended design happens when the team focuses on the act of development and deployment without any consideration of what will happen when people try to use it. — User Interface Engineering
11. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
12. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
13. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
14. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
15. Before you design, you figure out what needs to be accomplished. The research will drive the design. — Jared Spool
16. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
17. Not just discrete activities, but all the things that happen between activities. — UIE
18. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
19. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
20. — UIE Not just discrete activities, but all the things that happen between activities.
21. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
22. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 Used by permission. © 2012 The LEGO Group.
23. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 USE EXPERIENCE DESIGN WHEN Game changing innovation is *truly* a top priority A holistic experience would be greatly valued by the user You have the resources to invest into in-depth, 1:1 user research, preferably before you design an API
24. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources initial focus on complexity and ease of use developing for users beyond ourselves designing something we've never designed before need to fill the gaps between activities
25. CONDUCTING USER RESEARCH
26. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 Market Research User Experience Research What people say What people do
28. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 Market Research User Experience Research What people say What people do What people will buy How people use a product or service Demographics Ethnographics
29. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
30. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 Market Research User Experience Research What people say What people do What people will buy How people use a product or service Demographics Ethnographics Large sample sizes Small sample sizes Broad insight Deep, focused insight
31. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 5 STEPS OF USER RESEARCH 1. Identify research method 2. Figure out who to interview 3. Conduct the research 4. Review findings 5. Act on the findings
32. 1: IDENTIFY RESEARCH METHOD
33. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 METHODS OF USER RESEARCH user interviews contextual inquiries questionnaires focus groups card sorting eye-tracking click tracking tree tests journaling
34. 2. FIGURE OUT WHO TO INTERVIEW
35. 3. CONDUCT THE RESEARCH
36. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 CONDUCT THE RESEARCH Inform user that they are not being tested Ask user to think aloud as they work Confirm that they consent to being recorded
37. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 AS THEY WORK How do they get started? Time from desire to first request. How do they find and utilize documentation? How do they discover where to register or update configuration settings with you. What is their debugging process? What errors do they encounter and how do they diagnose and resolve them? How do they verify that they have properly integrated the API? What causes them to feel confident to push to production?
38. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 OTHER OBSERVATIONS Who made the decision to use your API? Are you replacing or augmenting existing functionality? Are you a new feature? What's their level of familiarity with the process that's being fulfilled? What external resources outside do they need to complete the tasks with your API? Are there interactions between the end users that you're uniquely facilitating for them?
39. 4. REVIEW FINDINGS
40. 5. ACT ON FINDINGS
41. Rocket Surgery Made Easy: The Do-It-Yourself Guide to Finding and Fixing Usability Problems — Steven Krug
42. ELEMENTS OF A GREAT API DESIGN
43. THE SECRET TO MACHINES TALKING TO MACHINES IS TO BE HUMAN
44. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 UX HIERARCHY OF NEEDS PLEASURABLE USABLE RELIABLE FUNCTIONAL — Aarron Walter, “Designing For Emotion”
45. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
46. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 UX HIERARCHY OF NEEDS PLEASURABLE USABLE RELIABLE FUNCTIONAL — Aarron Walter, “Designing For Emotion”
47. Amazon has both SOAP and REST interfaces to their web services, and 85% of their usage is of the REST interface. — Jeff Barr, Amazon, Chief Web Services Evangelist
48. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 UX HIERARCHY OF NEEDS PLEASURABLE USABLE RELIABLE FUNCTIONAL — Aarron Walter, “Designing For Emotion”
49. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
50. <form method="post" action="/orders">
51. SOAP: 51,393 vs. cURL: 9,041
52. <PutObject xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <Bucket>quotes</Bucket> <Key>Nelson</Key> <Metadata> <Name>Content-Type</Name> <Value>text/plain</Value> </Metadata> <Metadata> <Name>family</Name> <Value>Muntz</Value> </Metadata> <ContentLength>5</ContentLength> <AccessControlList> <Grant> <Grantee xsi:type="CanonicalUser"> <ID>a9a7b886d6241bf9b1c61be666e9</ID> <DisplayName>chriscustomer</DisplayName> </Grantee> <Permission>FULL_CONTROL</Permission> </Grant> <Grant> <Grantee xsi:type="Group"> <URI>http://acs.amazonaws.com/groups/global/AllUsers<URI> </Grantee> <Permission>READ</Permission> </Grant> </AccessControlList> <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId> <Timestamp>2007-05-11T12:00:00.183Z</Timestamp> <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature> </PutObject>
53. PUT /my-image.jpg HTTP/1.1 Host: myBucket.s3.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB +FIEXAMPLE= Content-Type: text/plain Content-Length: 11434 Expect: 100-continue [11434 bytes of object data]
54. DX DESIGN PATTERNS
55. We'll begin with a recap of REST, Representational State Transfer 1
56. REST Recap GET /orders -> Find all orders (200 OK) POST /orders -> Create a new order (201 Created) GET /orders/123 -> Find Order #123 (200 OK) PUT /orders/123 -> Update Order #123 (200 OK) DELETE /orders/123 -> Delete Order # 123 (204 No Content) 1
57. REST Recap GET /orders Accept: application/json 1
58. URL parameters or JSON input? 2
59. URL parameters or JSON input? /orders?order_date=2013-03-10 2
60. URL parameters or JSON input? PUT /orders/123 Accept: application/json { "customer_id": 948, "order_date": "2013-03-10", "shipping_address": … } 2
61. It's ok to break the REST architecture in the name of UX 3
62. Breaking REST for UX PUT /orders/123.json?body={"customer_id": 948,"order_date": "2013-03-10","shipping_address": …} 3
63. Considerations for parameter names 4
64. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 4 - PARAMETER NAMES Don't abbreviate parameter names. Pick a naming convention and don't deviate: camelCase, hyphenated-nouns, underscored_nouns HTML id and classes should not use underscores, but JavaScript object keys should not use hyphens, and camelCasing introduces error-prone case sensitivity. Pick one and stick with it. Booleans should use 'true' and 'false'. 1/0 and t/f are not explicit. Dates should be represented as a subset ISO 8601 (2013-03-22T12:00:00.0Z). Assume dates passed to the server are in UTC.
65. 4 ISO 8601 was published on 06/05/88 and most recently amended on 12/01/04. http://xkcd.com/1179/
66. Don't expose internal IDs 5
67. Pagination 6
68. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 6 - PAGINATION To modify the results, use: a 'sort_type' parameter to specify which attribute to sort on a 'sort_order' parameter to specify ascending or descending a 'per_page' parameter to specify the number of results per page a 'page' parameter to specify which page an 'offset' parameter to specify the number of records to offset the results by that would override the 'page' parameter
69. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 6 - PAGINATION And in the results returned, it's useful to have a pagination object that notes: the current page the current offset the last offset to denote when you're out of results
70. Pagination { "orders": [], "pagination": { "per_page": 6, "offset": 37, "last_offset": 40, "total_results": 40 } } 6
71. Provide awesome errors 7
72. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 7 - PROVIDE AWESOME ERRORS 400 Bad Request 401 Unauthorized 404 Not Found 405 Method Not Allowed 409 Conflict 410 Gone 500 Internal Server Error 503 Service Unavailable
73. Provide awesome errors { "error": { "type": "invalid_request_error", "message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/ api#authentication for details, or we can help at https:// support.stripe.com/." } } 7
74. Provide smart caching headers 8
75. Rate limits 9
76. Rate limits X-FeatureRateLimit-Limit X-FeatureRateLimit-Remaining X-FeatureRateLimit-Reset 9
77. Batch endpoints 10
78. Batch endpoints curl \ -F 'access_token=…' \ -F 'batch=[{"method":"GET", "relative_url":"me"},{"method":"GET", "relative_url":"me/friends?limit=50"}]' \ https://graph.facebook.com [ { "code": 200, "headers":[ { "name": "Content-Type", "value": "text/javascript; charset=UTF-8" } ], "body": "{\"id\":\"…\"}"}, { "code": 200, "headers":[ { "name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ], "body":"{\"data\": [{…}]}} ] 10
79. HTTPS 11
80. Offer CORS and JSON-P 12
81. Offer CORS and JSON-P /orders?callback=foo <script> function foo(data) { /* do something */ } </script> <script src="/orders?callback=foo"></script> foo({"real_data":true, "id": 123}); Go to http://enable-cors.org/ to learn more. 12
82. OAuth 1 vs OAuth 2 vs API keys 13
83. Versioning 14
84. Webhooks 15
85. OEmbed 16
86. OEmbed http://www.youtube.com/oembed?url=http%3A//www.youtube.com/watch %3Fv%3DbDOYN-6gdRE { "provider_url": "http://www.youtube.com/", "author_name": "schmoyoho", "provider_name": "YouTube", "height": 344, "thumbnail_height": 360, "thumbnail_url": "http://i3.ytimg.com/vi/bDOYN-6gdRE/hqdefault.jpg", "type": "video", "version": "1.0", "thumbnail_width": 480, "html": "<iframe width=\"459\" height=\"344\" src=\"http:// www.youtube.com/embed/bDOYN-6gdRE?feature=oembed\" frameborder= \"0\" allowfullscreen></iframe>", "title": "Auto-Tune the News #8: dragons. geese. Michael Vick. (ft. T- Pain)", "author_url": "http://www.youtube.com/user/schmoyoho", "width": 459 } 16
87. Play to your strengths 17
88. Play to your strengths 17
89. Leverage infrastructure to assist non- functional requirements 18
90. Documentation 19
91. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 19 - API DOCUMENTATION HTTP Method Input parameters data type required? default value? all possible values? what it does Error Codes Related endpoints Rate Limit? Common use cases
92. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2
93. Testing accounts or environments 20
94. Logging 21
95. [status.you-api.com] 22
96. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 22 - API STATUS EXAMPLES https://status.github.com/ http://status.twilio.com/ https://developers.facebook.com/live_status
97. Support channels 23
98. Public Bug Reports and status 24
99. Developer Showcase 25
100. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 25 - DEVELOPER SHOWCASE Box.net: https://www.box.com/apps/ Eventbrite: http://eventbrite.com/partners Evernote: http://trunk.evernote.com/ Foursquare: https://foursquare.com/apps/ Pocket: http://getpocket.com/apps/ Salesforce App Exchange: https://appexchange.salesforce.com/
102. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 BREAK! 2013.03.11
103. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 SDK DESIGN Brian Smith, Dropbox 2013.03.11
104. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 PANEL DISCUSSION Brian Smith API Engineering Lead Dropbox R. Kevin Nelson API Engineer Rdio Neil Mansilla Director, Developer Platform and Partnerships Mashery Jeremiah Cohick
105. SLIDE TITLE BLOCK Item 1 sub item 1 sub item 2 sub item 3 Item 2 sub item 1 Item 3 sub item 1 sub item 2 http://dx.jeremiahlee.com/ THANKS FOR ATTENDING content available: Please support: