API docs frequently fail to address developers’ needs by omitting common usage scenarios and use cases. Let’s take a look at good and bad practices for documenting API use cases, and take steps to ensure that developers get from our API and docs what they really want. You wrote an API specification, documented your endpoints, and published SDKs. Here’s a question, though: Does your API actually solve your users’ problems? API providers often fail to address common use cases to solve users’ needs, or their assumptions don’t match the reality. This may end up in frustration and loss of users. In this talk, we will take a peek into developers’ mindset. I will show how to better understand the developers’ needs by researching the usage patterns, existing libraries and 3rd party experience layers, provide examples of good and bad practices, and suggest actionable steps to improve developer experience for your API.

1. Why Your API
Doesn’t Solve My Problem
Use Case-Driven API Design
Jan Vlnas
November 8, 2022

2. superface.ai
Hello, I’m Jan 👋
Developer Advocate @ Superface.ai
jan.vlnas.cz

3. superface.ai
API
You
Me

4. superface.ai
Why should I use your API?
To solve my problem.
To fulfill my app’s use cases.

5. superface.ai
Reset a password
“I need to send an email.”

6. superface.ai
Where’s my use case?

7. superface.ai
Here’s my use case!

8. superface.ai
Transactional
emails
Send password
reset email
API

9. superface.ai
Send password
reset email
Transactional
emails
API
Use case
Capability

10. superface.ai
API
Users don’t speak your language
“User account”
“Password reset email”
“Session”
“Account verification”
“Transactional emails”
“API token”
“Sender”
“Domain”

11. superface.ai
API
Map use case to
capability
???

12. superface.ai
“Monitor who gave a star to
a repository.”
On GitHub & GitLab

13. superface.ai
Repository
Stargazers
“Monitor who gave a star to
a repository.”
GraphQL
REST API

14. superface.ai
Project
Starrers
“Monitor who gave a star to
a repository.”
GraphQL
REST API

15. superface.ai
Domain
Mapping
Mapping
API

16. superface.ai
API
Domain
Rate limits?
Authentication?
Deprecations?
Business rules
Pricing?

17. superface.ai
Understand your problem domain
Understand your business rules
Figure out your API capabilities
Map app use cases to your
API capabilities
What users need to do

18. superface.ai
What should you do?

19. superface.ai
Treat your API as a product

20. superface.ai
Treat your API as a product
(with an owner)

21. superface.ai
Understand your users
&
their problem domain

22. superface.ai
Discover use cases
User research with users & partners

23. superface.ai
“What are you building?”
×
“Do you prefer REST
or GraphQL?”

24. superface.ai
Discover use cases
User research
Competitors

25. superface.ai
Can you improve on
competitors’ use cases?

26. superface.ai
Discover use cases
Users & Partners
Competitors
Code

27. superface.ai
Repository Search
Topics!

28. superface.ai
Multi-
provider
SDKs

29. superface.ai
Dependents

30. superface.ai
Awesome Lists

31. superface.ai
Present use cases
Solutions

32. superface.ai

33. superface.ai

34. superface.ai
Stripe Docs

35. superface.ai
Here.com: Product-Centered Docs

36. superface.ai
Present use cases
Solutions
Guides

37. superface.ai
Mews: Connector API Use Cases

38. superface.ai
Present use cases
Solutions
Guides
Tutorials

39. superface.ai
“Most developer tutorials are
not worth copying.
They're product tutorials when
what developers want are
use case tutorials.”
— Adam DuVander, EveryDeveloper

40. superface.ai

41. superface.ai
GitHub: Build a CI Server

42. superface.ai
Vonage: Contact Center Use Case

43. superface.ai
Use case-driven design

44. Research
Use Cases
REST / GraphQL / …
API Design
Implementation
Specification, Reference
Building an API

45. Research
Use Cases
REST / GraphQL / …
API Design
Implementation
Specification, Reference
Guides, Tutorials

46. superface.ai
Summary

47. superface.ai
Why your API doesn’t solve
my problem?
Because I can’t
understand it.

48. API specification
Reference
Product tutorials
Capabilities

49. Solutions
Guides
Use cases

50. Use case tutorials

51. superface.ai
Reference Use case
guides
Use case
tutorials

52. superface.ai
VW GEN.TRAVEL (CleanTechnica)
Autonomous Integrations

53. superface.ai
jan.vlnas.cz