The document discusses the importance of developer experience (DX) in API integration and consumption, emphasizing empathy and usability as key elements for successful platforms. It outlines strategies for creating effective API documentation using the Swagger framework, highlighting the need to cater to different types of users and stages of the developer journey. Additionally, it provides recommendations for documentation best practices to enhance user engagement and adoption.

1. API Developer Experience:
Why it Matters, and How Documenting
Your API with Swagger Can Help

2. Meet Today’s SwaggerHub Team
Product Marketing Manager:
Keshav Vasudevan
@keshinpoint
Marketing Manager:
Ryan Pinkham

3. Agenda
•What is Developer Experience (DX)?
•What does it mean for an API to have good DX?
•How to think through DX
•How to build effective Documentation
•An introduction to the Swagger framework
•Designing APIs from a usability perspective
using Swagger and SwaggerHub

4. What is Developer Experience
(DX)?

5. The Multi Platform Ecosystem
•A Platform is a Product that can be extended by
users for the benefit of others
•APIs have enabled products to become
platforms more easily by lowering the
communication barrier between products
Average consumer
Third party developer

6. Developers are Humans Too
Developer experience is an extension of UX
that focuses on the developer integrating and
consuming your Platform
•DX is the aggregate of all the experiences a
developer has when interacting with your
Platform, usually through an API
•It’s an emotive experience, irrespective of the
value of the service your Platform provides

7. Why DX Matters
•Information, no matter how useful it is, won’t be
consumed well if the experience is not
presented in the right way
•Network effect – Users complain about your API
to their friends
•Switch effect - If your competitors have a better
DX, users will have a huge incentive to switch
We do better with products and platforms we
enjoy using

8. The implications of DX
•Good DX could lead to
–Improvement to Platform
–Evangelism and word-of-mouth growth
–Higher adoption and usage
Usability does not triumph Utility

9. Public APIs
•Goal: High Adoption
Why DX Matters (Contd)
Private APIs
•Goal: Low Cost
Partner APIs
•Goal: High Adoption, Low Cost

10. How to Think Through
Developer Experience

11. Empathy is the guiding force of good DX
•Good DX has two goals- help the user to help
the business objective
•An API with characteristically good DX is guided
by customer empathy and product management
principles
–Understand at which stage devs will use your API
–Understand why and how they plan on doing it

12. DX is the sweet spot between Biz, Tech, User

13. Recommendations on thinking through DX
1. Understand your Audience
2. Understand their Journey
3. Map this Journey to the Right Audience
Guiding Principle: the 3:30:3 rule

14. 1. Understand your Audience
Understand who needs your Documentation
API Users
Newcomer -
First Time
User
Debugger –
addressing a
specific issue
Evaluator-
Deciding
whether to
use the API
Problem Solver –
Is X possible
with this API
API Decision Makers
Eg: Front end Dev Eg: Back end Dev Eg: CTO Eg: PM

15. Your Audience is Smart
“Marketing to Developers is giving them Legos
and guiding them to build a Spaceship”
-Kirsten Hunter

16. 2. Understand their Journey
Why should I
use it?
How do I
register?
Where do I
start?
How do I use it?
•A well designed API will cater to optimal DX
across every stage of the Developer Journey
•APIs with good DX are built for sustainability
and long last – it’s not a temporary and short
term endeavor

17. 3. Map this Journey to the Right Audience
Why should I
use it?
How do I
register?
Where do I
start?
How do I use it?
Focus: Decision Makers Focus: Decision
Makers, API Users
Focus: API Users,
Decision Makers
Focus: API Users
Product Marketing Documentation

18. Follow the 3:30:3 Rule
3:30:3 Rule
•3 seconds to understand API’s purpose
•30 seconds to identify entry point into system
•3 minutes to use the API’s result

19. 3.a. “Why Should I use it”?
Why should I
use it? Focus: Decision Makers
•Provide the right positioning to your API based
on your industry
•Message your API’s value in a way that
resonates with the problems developers are
trying to solve
•The 3 second rule – People should understand
your API’s value in 3 seconds

20. Examples
Twilio
Know exactly what the value is,
and what it’s mean to be used for

21. Examples
Dropbox
Pleasant to read,
easy to understand,
with example use
cases, all in the first
section of the
landing page

22. •Decision makers and Users, both want to try
your API
•First step is to obtain an API key
•Recommendations:
–Explain setup in a comprehensive fashion
–Engineer registration with minimal steps
–Add an API Explorer/Console
3.b. “How Should I Register and Get Started”?
How do I register?
Focus: Decision Makers,
API Users

23. Examples
Make Sign Up straightforward
Dropbox asks you for your name, email and password for the free API key. It
also allows Google sign in. Straightforward process with Mailchimp as well.

24. Bad Examples
Jumping through
Hurdles -
SoundCloud
SoundCloud asks users to
fill up a 3 page Google
form, with details on the
app idea, before awarding
the API key. Waiting
period is typically 2 weeks

25. 3.c. “How Do I Start and Use it”
•An API is only as good as its documentation
•Documentation is deliverable of technical
content, containing instructions on to effectively
use your API – usage manual
•Good documentation can be a determining
factor is API adoption and growth
Where do I
start?
How do I use it?
Documentation

26. Examples

27. How to Build Effective
Documentation

28. Effective Documentation Tips
•Documentation plays a central role in the way
APIs are perceived by a User
•Tip 1: List the Fundamentals
•Tip 2: Write for Humans (Ease of Reading)
•Tip 3: Explain your Request-Response Cycles
•Tip 4: Empower with Experimentation

29. Tip 1: List the Fundamentals
Fundamental Sections in every documentation
Authentication Errors End Points
Terms of Use Changelog

30. Tip 2: Write for Humans
Never Assume
Audience is 100% developers Developers are fully familiar
with API/Domain Jargon
•Strive to make documentation readable by
Evaluators
•Provide context and information for jargon and
domain specific words

31. Examples

32. Tip 3: Explain your Request-Response Cycles
•Your API Users should know exactly what to
expect from a successful call
•Describe full sample response body in every
supported format
•Focus not just on the response format, but also
HTTP response headers and error codes
1. Examples in Use Cases
2. Examples in Request-Response Cycles

33. Examples
Stripe
All the Error Codes are
described in a separate
section for users to follow

34. Examples
YouTube
Well detailed parameters,
with an overview section
of every resource. These
resources are all
organized in an easy to
follow navigation pane

35. Tip 4: Experimentation is Power
The difference between documentation and
good documentation is a little more effort with
these Nice-to-haves.
Allow developers to experiment with your API
1. Getting Started Guides
2. Interactive Docs and Console
3. SDKs
4. Tutorials

36. Examples
Braintree

37. Examples
API Console
Microsoft Graph Explore lets you try various end points and see what the
response packet is

38. How Swagger framework fits in
to your API Documentation

39. Swagger is the contract for your API
•Swagger is an API framework, that allows users
to
–Design
–Build
–Document
•Swagger defines your API’s contract
•Connects computers, technology stacks and
humans in one unified language

40. Example of a Swagger API Contract

41. Example of Documentation

42. Example of Documentation

43. Demo

44. Demo: Meetup API Team
• API Objective
–Allow developers to access information and
use the information from meetups
(https://meetups.com)
• API Overall Message
–Extend your Community
• API Description
–The Meetup API provides simple RESTful HTTP and streaming
interfaces for extending your community using the Meetup platform
from your own apps.

45. “Why Should I Use It?”

46. “How do I Register?”

47. “How Do I Use it?”
Start Documenting!

48. SwaggerHub is the center of your API lifecycle
Design
Implementation
Testing
Mocking
Documentation
Virtualization
Deployment /
Runtime
Clients
Configure AWS API
Gateway deployment
Developer portals,
Code samples, User guides
Functional / Runtime simulations
Functional, Security,
Load, Compliance
Generate AWS Lambda functions / configurations
Prototyping
30+ languages
Collaborative, Integrated

49. Resources
YouTube Channel Name: swaggerhub
Twitter Handle: @swaggerhub
Help: https://swaggerhub.com/help
Next Free Training Webinar: Mar 1, 10-11 AM ET

50. Thank you