API Developer Experience: Why it Matters, and How Documenting Your API with Swagger Can Help
-
Upload
smartbear-software -
Category
Software
-
view
92 -
download
2
Transcript of API Developer Experience: Why it Matters, and How Documenting Your API with Swagger Can Help
API Developer Experience: Why it Matters, and How Documenting
Your API with Swagger Can Help
Meet Today’s SwaggerHub Team
Product Marketing Manager:Keshav Vasudevan
@keshinpoint
Marketing Manager:Ryan Pinkham
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
What is Developer Experience
(DX)?
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
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
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
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
Public APIs
•Goal: High Adoption
Why DX Matters (Contd)
Private APIs
•Goal: Low Cost
Partner APIs
•Goal: High Adoption, Low Cost
How to Think Through
Developer Experience
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
DX is the sweet spot between Biz, Tech, User
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
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
Your Audience is Smart
“Marketing to Developers is giving them Legos
and guiding them to build a Spaceship”
-Kirsten Hunter
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
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
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
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
Examples
TwilioKnow exactly what the value is,
and what it’s mean to be used for
Examples
DropboxPleasant to read,
easy to understand,
with example use
cases, all in the first
section of the
landing page
•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
Examples
Make Sign Up straightforwardDropbox 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.
Bad Examples
Jumping through
Hurdles -
SoundCloudSoundCloud 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
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
Examples
How to Build Effective
Documentation
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
Tip 1: List the Fundamentals
Fundamental Sections in every documentation
Authentication Errors End Points
Terms of Use Changelog
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
Examples
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
Examples
StripeAll the Error Codes are
described in a separate
section for users to follow
Examples
YouTubeWell detailed parameters,
with an overview section
of every resource. These
resources are all
organized in an easy to
follow navigation pane
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
Examples
Braintree
Examples
API ConsoleMicrosoft Graph Explore lets you try various end points and see what the
response packet is
How Swagger framework fits in
to your API Documentation
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
Example of a Swagger API Contract
Example of Documentation
Example of Documentation
Demo
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.
“Why Should I Use It?”
“How do I Register?”
“How Do I Use it?”
Start Documenting!
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 / configurationsPrototyping
30+ languages
Collaborative, Integrated
Resources
YouTube Channel Name: swaggerhub
Twitter Handle: @swaggerhub
Help: https://swaggerhub.com/help
Next Free Training Webinar: Mar 1, 10-11 AM ET
Thank you