was just the first part of the internet's story. We’re now witnessing the idea of *division of labor* being applied via the internet. We're no longer limited to sharing information. Web service APIs have given us the ability to share our specialized capabilities with each other. And this means that not only can we do more, but that we can do more, more easily. I don't need to tell you—here at APIdays—about the benefits of using API products. What I would like to convince you of is the value in applying User Experience research and design methodologies to the API products you're responsible for. Because together, we can do so much. If we believe that building things together is the best use of our skills and time, it makes sense to help others help us.
1.0a OAuth 2.0 snake_case camelCase RPC What we usually talk about when we discuss improving our API is the actual design of the API. We debate the merits of RPC and SOAP and REST and Hypermedia design patterns, XML versus JSON, OAuth 1/2 or other authentication mechanisms, snake_case versus camelCase, URL parameters versus JSON objects. And while these are important conversations to have and while they do impact developer experience, an API is just an interface… a user interface. And UX is much more than just UI.
So ware Engineering Body of Knowledge (SWEBOK) by IEEE Computer Society (2004) Customer Requirements Requirements Specification Functional Specification Design Specification Validation Review Verification Study the requirements Clarify the requirements Write the so ware Test the so ware Validate against requirements Review with customer Define new requirements Software Development Life Cycle What sticks out to me most in this diagram is how much of software development is not programming. This (pointing to "write the software") is when the interface—the API—is critical to the experience. This (the rest of the diagram) is when it's not.
Emotion When we look holistically at a solution to a problem, we're evaluating the quality of a solution on multiple levels. I think a translation of Maslow's Hierarchy of Needs is appropriate for this evaluation. The one I like to reference is by Aarron Walter from his book, Designing for Emotion. We start with *functional* — The API has to solve the problem it claims to solve. Simple enough. But let's think for a moment about why someone would choose to use an API instead of doing it themselves. Most APIs replace some existing known way of doing something, but they need to do it so much better in order to convince people to use them. For example, SendGrid not only replaces SMTP, it does SMTP better than you could ever do it yourself. They're experts at deliverability and keeping your email out of spam folders. So not only do they solve a problem, they solve a problem very well.
FUNCTIONAL UX Hierarchy of Needs — Aarron Walter, Designing For Emotion But that functionality's existence is only as good as it's *reliability*. Reliability is really one of several non-functional requirements. availability (uptime), scalability (load and response time), stability (consistency), security. These -ilities don't matter if you don't provide the functionality, but no one is going to use an API if it can't be relied upon. Trust is important. Not only do you do what you say you will do, but you do so reliably.
Needs — Aarron Walter, Designing For Emotion Moving up the pyramid, we get to *usability*. Usability is a special requirement because it takes several forms: - intuitability: This is how quickly and easily the functionality can be obtained. This is largely the design of the API. - testability: How easily can developers confirm their implementation is correct? - The last form is corrective guidance, aka error handling. This is especially important because some errors happen at implementation and some happen at runtime based on input. Whether it's the API's, the developer's, or the end user's fault, everyone is disappointed when an error happens. How an API handles errors and how you help developers handle errors so that a situation can be corrected is critical to usability.
Walter, Designing For Emotion At the very top, we have *pleasurable* — This is the overall enjoyment and maximum value creation of the product. It's not just surprising and delighting your users, but solving a problem better than any other way. Using your API feels like the obvious solution to a problem at this stage. People are throwing money at you. ["TAKE MY MONEY!"] For me, I think of Twilio here. While I could run my own SMS gateway and work with telephone companies, I'd rather just let Twilio deal with it because they handle every detail of SMS much better than I ever could and they do it cost effectively. So looking at the pyramid: These bottom two rows are what convince a great developer there is a better way to do something they've done before. The next row is what convinces a developer to actually act because it's so easy to unlock the value proposition. The top row is when you've fulfilled the promise of division of labor 2.0. Your specialty has become someone else's super power. They are stronger even though they have an external dependency and willingly engage you. And again, API design is important—it's the majority of the usability layer—but it takes so much more than a well designed API to provide a great developer experience. Many of these elements above and below are invisible when perfect, but are sources of pain and confusion when imperfect. The only way you can identify and resolve these elements is by talking with your users.
applied science. Breaking that down further: Empathy is the ability to understand, anticipate, and share the feelings of another person. And an applied science is the discipline of using knowledge gathered via the scientific method to solve practical problems.
about our users—their struggles and their motivations —and then applying that knowledge to make it easier for them to satisfy their desires by using our products. UX is a broad term that incorporates many disciplines, but ultimately, it is a research-driven approach to design.
Engineering Research Costs Time Resources initial focus on complexity and ease of use developing for users beyond ourselves designing something we've never designed need to fill the gaps between activities Unintentional Self Genius Activity Focused Experienced Focused To quote them: "The order reflects the increasing amount of *research* the team employs to make decisions. While one could also think of the order as a growing maturity of the team, it turns out that each one has its place. Some projects don't warrant the costs, time, and resources necessary for extensive user research, but other projects will fail without it." The key word here is 'research'. What Jared Spool is saying is that in order to take an API from mediocre to awesome, we need to know more information about the people using the product to make informed decisions.
towards user's goal 2. Inform user of next step • User research reveals workflow context • Assumptions are dangerous: • Yours: blind to issues because of familiarity • Users': anti-pattern implementations
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?
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?
users, particularly when usage increases or decreases • Monitor support requests • Type (API bug, user bug, approach inquiry, etc) • Time to resolution • Stage of integration • Comprehension of API
jeremiahlee
javiergs
tsucchinoko
tsoshiro
thehaigo
uskey512
tnagao7
pyama86
ymd65536
d_endo
kiwasaki
nagise
jlugia
trallard
tammyeverts
bkeepers
afnizarnur
nonsquared
maggiecrowley
ddemaree
jnunemaker
eileencodes
mza
honnibal
