Conference talk at DevRelCon London 2019. 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. How to embed UX
thinking in API design
Steph Shin Lloyd
Devrelcon London 2019

2. Contents
2

3. 3

4. 4
● Cross-functional teams
● Organized by problem space
not discipline
● Platform product line
● App store billing domain
● Highly technical space

5. 5
● 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

6. 6

7. “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
7

8. REST vs.
GraphQL
8

9. in an
API or any DevRel product?
9

10. Application
Programming
Interface
10

11. 11

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

13. Developers are people too!
13

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

15. if Docs = Interface
and Developer = user
then using Docs = UX
15

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

17. 17
“[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

18. • 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)
18

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

20. ● Who will be using this?
● 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?
UX Questions
20

21. 21

22. in DevRel
products like API’s?
22

23. Collaborate out of the box
Don’t rule anyone out! Be open to the wealth of
insights and ideas that people of diverse
backgrounds and experiences bring to the
process, even if it’s out of their domain.
NOTE: Create opportunities for cross-collaboration within the
teams you work with and represent. Advocate for a culture of
collaboration and raise the bar.
23

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

25. Research what came before
Don’t have to reinvent the wheel. Look to
related examples to understand the thinking
behind the solution. Try to piece together the
narrative 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.
25

26. 26

27. Connect with people
Don’t rely solely on personas. Talk to the
people who use the product 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.
27

28. “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
28

29. 29
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?”
⛔
��

30. Model the concepts
Map out and visualize the objects &
relationships involved. Use this to align on the
system, taxonomy and schema.
NOTE: Focus on organizing and articulating how everything
relates to each other. It’s helpful to think of journeys or use
analogies to help you illustrate the concepts.
30

31. 31

32. 32

33. 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

34. 34

35. 35

36. 36

37. Embed UX in DevRel products
● Collaborate out of the box
● Research what came before
● Connect with people
● Model the concepts
● Test out the usability
Recap
37

38. other than what
an API is or how GraphQL works.
38

39. Personal
learnings
39
Focus on the what the
word represents. Finalize
the terminology later.
Avoid conflating similar
but separate concepts.
Balance the product
vision with user feedback
and data.

40. Personal
learnings
40
Focus on the what the
word represents. Finalize
the terminology later.
Avoid conflating similar
but separate concepts.
Balance the product
vision with user feedback
and data.

41. Usage fees in REST
41

42. Usage fees in GraphQL
42

43. Personal
learnings
43
Focus on the what the
word represents. Finalize
the terminology later.
Avoid conflating similar
but separate concepts.
Balance the product
vision with user feedback
and data.

44. Go forth and UX your DevRel

45. Questions & compliments
welcome 😉