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.
● Cross-functional teams
● Organized problem spaces not discipline
● Platform product line
● App store billing domain
● Highly technical space
Context: UX designer at Shopify
● 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
“Instead of deﬁning the
structure of responses on
the server, the ﬂexibility is
given to the client.”
– Petr Bela, GraphQL in the age of REST APIs
REST vs. GraphQL
if API = Interface
and Developer = user
then using API = UX
Start by accepting the fact
that you are NOT the user!
“[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
● 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...
“Good design, when it’s done
well, becomes invisible. It’s
only when it’s done poorly
that we notice it.”
– Jared Spool
● 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:
Be open to the wealth of insights and
ideas that non-technical people bring to
the technical design process.
NOTE: Discussions can be diﬃcult because words often
hold many different deﬁnitions. Diagrams, models or a
glossary could help ensure better alignment.
“Teams that fail,
fail to listen to each other.”
– Brent Summers, Get over yourself: Collaboration is
the secret to great products
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 speciﬁc context.
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 inﬂuencing
interviewees with leading questions.
Example of a leading question:
“I saw you were having diﬃculty with the
navigation. What happened?”
“What was easy or diﬃcult about getting
to the content you wanted?”
“Leading questions rob us of
the opportunity to hear an
insight we weren’t
– Amy Schade, Avoid Leading Questions to Get Better
Insights from Participants
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.
Test out the usability
Whether hi- or lo-deﬁnition, ﬁnd 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 inﬂuencing your bias.
Steps to improve user experience
Model the concept
Test out the usability
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 speciﬁc
words and ﬁnalize the terminology later.
Taking a complex concept and
oversimplifying it can cause problems
when scaling. Try to avoid conﬂating
similar but separate concepts.
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.