Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Developer Experience: The UX of APIs

Developer Experience: The UX of APIs

Jeremiah Lee

March 11, 2013
Tweet

More Decks by Jeremiah Lee

Other Decks in Programming

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. 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. 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
  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 FIVE COMMON STYLES OF DESIGN Unintentional Self Genius Activity Focused Experienced Focused Research, Costs, Time, Resources
  7. 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
  8. 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
  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. 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
  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
  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. Before you design, you figure out what needs to be

    accomplished. The research will drive the design. — Jared Spool
  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. 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
  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
  17. 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
  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 Used by permission. © 2012 The LEGO Group.
  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 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
  20. 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
  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 Market Research User Experience Research What people say What people do
  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 Market Research User Experience Research What people say What people do What people will buy How people use a product or service Demographics Ethnographics
  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
  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 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
  25. 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
  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 METHODS OF USER RESEARCH user interviews contextual inquiries questionnaires focus groups card sorting eye-tracking click tracking tree tests journaling
  27. 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
  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 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?
  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 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?
  30. Rocket Surgery Made Easy: The Do-It-Yourself Guide to Finding and

    Fixing Usability Problems — Steven Krug
  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 UX HIERARCHY OF NEEDS PLEASURABLE USABLE RELIABLE FUNCTIONAL — Aarron Walter, “Designing For Emotion”
  32. 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
  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 UX HIERARCHY OF NEEDS PLEASURABLE USABLE RELIABLE FUNCTIONAL — Aarron Walter, “Designing For Emotion”
  34. 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
  35. 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”
  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
  37. <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>
  38. 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]
  39. 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
  40. URL parameters or JSON input? PUT /orders/123 Accept: application/json {

    "customer_id": 948, "order_date": "2013-03-10", "shipping_address": … } 2
  41. 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.
  42. 4 ISO 8601 was published on 06/05/88 and most recently

    amended on 12/01/04. http://xkcd.com/1179/
  43. 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
  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 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
  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 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
  46. 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
  47. 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
  48. 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
  49. 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
  50. 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
  51. 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
  52. 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
  53. 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/
  54. 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
  55. 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
  56. 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
  57. 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: