Pro Yearly is on sale from $80 to $50! »

Developer Experience: The UX of APIs

Developer Experience: The UX of APIs

A1bbf2de1c3ef1db1c54d77d2ab17de2?s=128

Jeremiah Lee

March 11, 2013
Tweet

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
  27. None
  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/
  101. None
  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: