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
(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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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?
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?
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
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.
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
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
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
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
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
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
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
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