Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
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...
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 e...
Developers are Humans Too
Developer experience is an extension of UX
that focuses on the developer integrating and
consumi...
Why DX Matters
•Information, no matter how useful it is, won’t be
consumed well if the experience is not
presented in the ...
The implications of DX
•Good DX could lead to
–Improvement to Platform
–Evangelism and word-of-mouth growth
–Higher adopti...
Public APIs
•Goal: High Adoption
Why DX Matters (Contd)
Private APIs
•Goal: Low Cost
Partner APIs
•Goal: High Adoption, Lo...
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 ...
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 ...
1. Understand your Audience
Understand who needs your Documentation
API Users
Newcomer -
First Time
User
Debugger –
addres...
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 AP...
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...
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.a. “Why Should I use it”?
Why should I
use it? Focus: Decision Makers
•Provide the right positioning to your API based
o...
Examples
Twilio
Know exactly what the value is,
and what it’s mean to be used for
Examples
Dropbox
Pleasant 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...
Examples
Make Sign Up straightforward
Dropbox asks you for your name, email and password for the free API key. It
also all...
Bad Examples
Jumping through
Hurdles -
SoundCloud
SoundCloud asks users to
fill up a 3 page Google
form, with details on t...
3.c. “How Do I Start and Use it”
•An API is only as good as its documentation
•Documentation is deliverable of technical
c...
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 ...
Tip 1: List the Fundamentals
Fundamental Sections in every documentation
Authentication Errors End Points
Terms of Use Cha...
Tip 2: Write for Humans
Never Assume
Audience is 100% developers Developers are fully familiar
with API/Domain Jargon
•Str...
Examples
Tip 3: Explain your Request-Response Cycles
•Your API Users should know exactly what to
expect from a successful call
•Des...
Examples
Stripe
All the Error Codes are
described in a separate
section for users to follow
Examples
YouTube
Well detailed parameters,
with an overview section
of every resource. These
resources are all
organized i...
Tip 4: Experimentation is Power
The difference between documentation and
good documentation is a little more effort with
t...
Examples
Braintree
Examples
API Console
Microsoft 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 ...
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:...
“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
Deployme...
Resources
YouTube Channel Name: swaggerhub
Twitter Handle: @swaggerhub
Help: https://swaggerhub.com/help
Next Free Trainin...
Thank you
Upcoming SlideShare
Loading in …5
×

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

1,284 views

Published on

Whether you’re new to Swagger, or have already been using the framework for API design, there’s a good chance you still have questions about how to improve your API documentation. Creating API documentation your consumers will love can take some work, but the investment will have a significant payoff in the form of a great developer experience, easier implementation, and improved adoption of your API.

This presentation covers good developer experience in detail, focusing on why and how to provide an optimal experience for developers using your API. We will also cover how Swagger has changed the API design and documentation landscape, and finally show some good practices for API documentation using Swagger in SwaggerHub’s integrated API development platform.

Things to expect in this webinar:

What is Developer Experience (DX)?
What does it mean for an API to have good DX?
API documentation in the context of good DX?
An introduction to the Swagger framework
Designing APIs from a usability perspective using Swagger and SwaggerHub

Published in: Software
  • Be the first to comment

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

  1. 1. API Developer Experience: Why it Matters, and How Documenting Your API with Swagger Can Help
  2. 2. Meet Today’s SwaggerHub Team Product Marketing Manager: Keshav Vasudevan @keshinpoint Marketing Manager: Ryan Pinkham
  3. 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. 4. What is Developer Experience (DX)?
  5. 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. 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. 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. 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. 9. Public APIs •Goal: High Adoption Why DX Matters (Contd) Private APIs •Goal: Low Cost Partner APIs •Goal: High Adoption, Low Cost
  10. 10. How to Think Through Developer Experience
  11. 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. 12. DX is the sweet spot between Biz, Tech, User
  13. 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. 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. 15. Your Audience is Smart “Marketing to Developers is giving them Legos and guiding them to build a Spaceship” -Kirsten Hunter
  16. 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. 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. 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. 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. 20. Examples Twilio Know exactly what the value is, and what it’s mean to be used for
  21. 21. Examples Dropbox Pleasant to read, easy to understand, with example use cases, all in the first section of the landing page
  22. 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. 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. 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. 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. 26. Examples
  27. 27. How to Build Effective Documentation
  28. 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. 29. Tip 1: List the Fundamentals Fundamental Sections in every documentation Authentication Errors End Points Terms of Use Changelog
  30. 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. 31. Examples
  32. 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. 33. Examples Stripe All the Error Codes are described in a separate section for users to follow
  34. 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. 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. 36. Examples Braintree
  37. 37. Examples API Console Microsoft Graph Explore lets you try various end points and see what the response packet is
  38. 38. How Swagger framework fits in to your API Documentation
  39. 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. 40. Example of a Swagger API Contract
  41. 41. Example of Documentation
  42. 42. Example of Documentation
  43. 43. Demo
  44. 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. 45. “Why Should I Use It?”
  46. 46. “How do I Register?”
  47. 47. “How Do I Use it?” Start Documenting!
  48. 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. 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. 50. Thank you

×