At the heart of scalable and intuitive APIs is great user experience, but the UX of an API is rarely considered. Learn how to integrate UX strategies to create improved API experiences using real life examples and lessons learned from upgrading Shopify’s own API.

1. Steph Shin
UX thinking in API design

2. ● Cross-functional teams
● Organized problem spaces not discipline
● Platform product line
● App store billing domain
● Highly technical space
Context: UX designer at Shopify

3. ● Serves third party app developers
● Allows app developers to charge Shopify
Merchants directly through their store account
● Originally built in REST
● Our goal was to build it in GraphQL
● Launch at Shopify Unite 2019
Context: Shopify’s Billing API

5. “Instead of defining the
structure of responses on
the server, the flexibility is
given to the client.”
– Petr Bela, GraphQL in the age of REST APIs

6. REST vs. GraphQL
Source: https://medium.com/chute-engineering/graphql-in-the-age-of-rest-apis-b10f2bf09bba

7. Why would I need to think
about UX for an API?

8. Application
Programming
Interface

10. “An API is first & foremost
an interface for people”
– Arnaud Lauret, The Design of Web APIs

11. Developers are people too.

12. if API = Interface
and Developer = user
then using API = UX

13. Start by accepting the fact
that you are NOT the user!

14. “[Users] are usually very different than
those who write the code, even [when]
they are developers: they have different
backgrounds, experiences with user
interfaces, mindsets, mental models,
and goals. They are not us.”
– Raluca Budiu, You Are Not the User: The
False-Consensus Effect

15. ● Trustworthy & consistent (even if it’s unpredictable)
● Human (even if it’s highly technical)
● Discoverable (even if it’s not the main star)
● Easy & simple (even if it’s challenging & complex)
Great UX should feel...

16. “Good design, when it’s done
well, becomes invisible. It’s
only when it’s done poorly
that we notice it.”
– Jared Spool

17. ● Who will be using this API?
● What problem does this solve?
● What are the use cases?
● What could get in the way of an enjoyable experience?
● How do users understand the problem space?
Helpful questions to guide the design of
great user experiences:

18. What does UX look like for
API’s?

19. Collaborate
Be open to the wealth of insights and
ideas that non-technical people bring to
the technical design process.
NOTE: Discussions can be difficult because words often
hold many different definitions. Diagrams, models or a
glossary could help ensure better alignment.

20. “Teams that fail,
fail to listen to each other.”
– Brent Summers, Get over yourself: Collaboration is
the secret to great products

21. Research precedents
Look to related or similar examples to
understand the thinking behind the
solution. Try to piece together what they
learned that led to their decisions.
NOTE: It’s not enough to simply copy. You’ll need to
understand how to apply it to your specific context.

23. Interview users
Talk to users directly and learn about their
current solutions, their motivations and
their mental models.
NOTE: It’s very easy to fall into biases. Be sure to work
with a researcher whenever possible to avoid influencing
interviewees with leading questions.

24. Example of a leading question:
“I saw you were having difficulty with the
navigation. What happened?”
Vs.
“What was easy or difficult about getting
to the content you wanted?”
⛔
��

25. “Leading questions rob us of
the opportunity to hear an
insight we weren’t
expecting.”
– Amy Schade, Avoid Leading Questions to Get Better
Insights from Participants

26. Model the concept
Map out and visualize the objects &
relationships involved. Use this to align
on the system, taxonomy and schema.
NOTE: Focus on organizing the objects and articulating
how they relate to each other and move through the
system. It’s helpful to think of journeys. Use analogies to
help you illustrate the concepts.

29. Test out the usability
Whether hi- or lo-definition, find a way to
present and test the core logic and
structures of the API design. This can be
done with, interviews, tree tests, surveys...
NOTE: Be as objective as possible and work with a
researcher when possible to avoid influencing your bias.

33. Steps to improve user experience
Collaborate
Research precedents
Interview users
Model the concept
Test out the usability

34. What did I learn?

35. Naming is hard!
Language has many layers of meaning
steeped in culture, past experiences and
individual biases. Focus on the what the
word represents rather than the specific
words and finalize the terminology later.

36. Oversimplification can
complicate things
Taking a complex concept and
oversimplifying it can cause problems
when scaling. Try to avoid conflating
similar but separate concepts.

37. Usage fees in REST

38. Usage fees in GraphQL

39. Not all feedback is equal
Find a balance between being descriptive
and prescriptive. You don’t have to act on
every feedback. Decisions should be
informed by the product vision as well as
user feedback and data.

40. Questions &
compliments welcome
😉