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