1.
Executing on API
Developer
Experience
Keshav Vasudevan
@keshinpoint
8th Nov 2017

2.
Page
Proprietary & Confidential
Increased Opportunities With PSD2
PSD2isa dataandtechnology-drivendirectivethataimsto-
IncreasecompetitionImproveinnovation
Encouragetransparency Addrevenuestreams
2

3.
Page
Proprietary & Confidential
Explosion in the API Economy
0.3 0.6 0.9
1.5
2.4
3.4
7.2
10.3
12.2
14.1
16.1
0
2
4
6
8
10
12
14
16
18
0 2006 07 08 09 10 11 12 13 14 15 16
9 Millon
developersworking
onprivateAPIs
85%
ofenterpriseswill
haveanAPIby2018
100,000
PublicAPIs
3

4.
Page
Proprietary & Confidential
The Multi Platform Ecosystem
A platform is a product that canbe extended by users for the benefit of others
Average consumer
Third party developer
4

5.
Page
Proprietary & Confidential
Examples of Platforms
5

6.
Page
Proprietary & Confidential
Developers Are Humans Too
DX is the aggregateof allthe experiencesa developer has when interactingwith your Platform,usually
through an API
6

7.
Page
Proprietary & Confidential
Why Developer Experience Matters?
Growth and Adoption: The value of anAPIincreases when users reachcriticalmass
PreventsSwitch: MakesAPIs differentiable and competitive
Helps drive business and technological goals
7

8.
Page
Proprietary & Confidential
We Do Better With Products We Enjoy Using
8

9.
How to Think About API
Developer Experience

10.
Page
Proprietary & Confidential
A DX Focus
Focusses on solving an actualhuman need
Focusses on driving the business
Focusses on sustainability
10

11.
Page
Proprietary & Confidential
3 Step DX Framework
Recommended for optimizing the DX of your API
Step 1
Understand the API’s
audience
Step 3
Map the audience to the journey
Step 2
Understand the
audience journey
11

12.
Page
Proprietary & Confidential
Step 1: Understand the API’s Audience
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: CTO Eg: PM
12

13.
Page
Proprietary & Confidential
Step 2: Understand their Journey
Why should I use
it?
How do I register? Where do I start? How do I use it?
13

14.
Page
Proprietary & Confidential
Step 3: Map 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: Decision
Makers, API Users
Focus: API Users
Product Marketing Design and
Documentation
14

15.
Optimizing Your API’s
Developer Experience

16.
Page
Proprietary & Confidential
Before We Proceed…Follow the 3:30:3 Rule
Credit: OriPekelman
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
16

17.
Page
Proprietary & Confidential
3.a. “Why Should I Use It”?
Focus:
Decision
Makers
Why should I
use it?
Position based on Industry Concise messaging of core
value
Understand value in 3
seconds
Recommendations
17

18.
Page
Proprietary & Confidential
Example: Stripe
18

19.
Page
Proprietary & Confidential
Example: PayPal
19

20.
Page
Proprietary & Confidential
3.a. “How Should I Register”?
Focus:
Decision
Makers
Why should I
use it?
Explain setup in a
comprehensive fashion
Minimal steps to register –
30 seconds
Provide API console
Recommendations
Focus:
Decision
Makers, API
Users
How do I
register?
20

21.
Page
Proprietary & Confidential
Example: CapitalOne DevExchange
21

22.
Page
Proprietary & Confidential
Example: Open Bank project
22

23.
Page
Proprietary & Confidential
Example: Dropbox; MailChimp
23

24.
Page
Proprietary & Confidential
Example: 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
24

25.
Page
Proprietary & Confidential
3.c.d “How Do I Use It”?
Focus:
Decision
Makers
Why should I
use it?
How do I
register?
Where do I
start?
How do I use
it?
Documentation
25

26.
API Documentation and the
OpenAPI Specification

27.
Page
Proprietary & Confidential
What is API Documentation?
• Describes how to be successful with the API
• Deliverable of technical writing
• Acts as the usage manual for the API
An API is only as good as its documentation
27

28.
Page
Proprietary & Confidential
Examples
28

29.
Page
Proprietary & Confidential
Traditional API Development and Documentation
Technical
Writer
Developer Tester
Architect
Request
Response

30.
Page
Proprietary & Confidential
Major Problems
Maintaining documentation, tests and implementation was always hard
Implementation always cameatthe cost of DX
Communication betweenservicesbuilt in different languages was hard
30

31.
Page
Proprietary & Confidential
RESTful Interface
Call the API
(request)
Obtain data
(response)
Restful
Interface
Technical
Writer
Developer Tester
Architect
Keeps in
Sync
31

32.
Page
Proprietary & Confidential
The OpenAPI Spec is the API’s Contract
• The OAS is an API descriptionformat to Design and Document REST APIs
• The OAS defines the API’s contract
• Connects computers, technologystacks and humans in one language
32

33.
Page
Proprietary & Confidential
Example of an OAS Defined API
Requests
Responses
API
Overview
33

34.
Page
Proprietary & Confidential
Example of Documentation
Hosted on SwaggerHub
34

35.
Page
Proprietary & Confidential
Creating Effective Documentation

36.
Page
Proprietary & Confidential
3.c.d “How Do I Use It”?
Focus:
Decision
Makers
Why should I
use it?
How do I
register?
Where do I
start?
How do I use
it?
Documentation
36

37.
Page
Proprietary & Confidential
Tips for Effective API Documentation
Tip 1: List the Fundamentals
Tip 2: Write for Humans
Tip 3: Explain your Request-Response Cycles
Tip 4: Empower with Experimentation
37

38.
Page
Proprietary & Confidential
Tip 1: List the Fundamentals
Authentication Errors End Points
Terms of Use Changelog
Examples
38

39.
Page
Proprietary & Confidential
Authentication in OAS
• OAuth 2
–Implicit
–Password
–Access Code
39

40.
Page
Proprietary & Confidential
End Points in OAS
40

41.
Page
Proprietary & Confidential
HTTP Codes and Examples in OAS
41

42.
Page
Proprietary & Confidential
Example: Changelog and Terms of Use
Box
Google
42

43.
Page
Proprietary & Confidential
Tip 2: Write for Humans
NeverAssume
Audience is 100% developers Consumers are fully familiar with
API/Domain Jargon
• Strive to make documentation readable by Decision Makers
• Start writing in plain English without jargon
• Provide context and information for jargon and domain specific words
• Maintain consistency of tone
43

44.
Page
Proprietary & Confidential
Examples: Stripe
44

45.
Page
Proprietary & Confidential
Tip 3: Explain Your Request-Response Cycles
• Your APIUsers should know exactlywhatto expectfrom a successful call
• Describe full sample response body in everysupported format
• Focus not just on the response format,but also HTTP response headers and error codes
• Provide enough context using examples
1. Examples in Use Cases
2. Examples in Request-Response Cycles
45

46.
Page
Proprietary & Confidential
Example: Stripe
46

47.
Page
Proprietary & Confidential
Tip 4: Experimentation is Power
Thedifferencebetweendocumentationandgooddocumentationisalittlemoreeffortwith
theseNice-to-haves.
Allow developers toexperiment withyour API
1. Getting StartedGuides
2. InteractiveDocs and Console
3. SDKs
4. Tutorials
47

48.
Page
Proprietary & Confidential
Examples: Braintree
48

49.
Page
Proprietary & Confidential
Examples: Microsoft Graph
49

50.
Page
Proprietary & Confidential
Example: Fidor
50

51.
Page
Proprietary & Confidential
Summary
• Good APIDeveloper Experience can help drive business and tech goals
• Threestep framework for understanding API DX
• Understand audience
• Understand journey
• Map journeytoaudience
• Tips for Good API Documentation
• List the Fundamentals
• Write for Humans
• Explain your Request-Response Cycles
• Empower with Experimentation
51

52.
Thank you!
@keshinpoint
keshav.vasudevan@smartbear.com