Your API documentation

powered by AI
Herve Roussel
Co-Founder at Quod AI

@hvroussel @quod_ai
 Most API docs suck

Only 35% of API providers feel that their API doc is

above average.
57% say that API doc was top priority.

Source: State of API 2019 Report, SmartBear (2019)

@hvroussel @quod_ai
 Obstacles for quality API

Lack of resources, time, and

tooling support are the biggest
obstacles to implementing a
successful API documentation
process

Source: State of API 2019 Report, SmartBear (2019)

@hvroussel @quod_ai
 What devs expect from APIs

Most important needs

for APIs

1. Ease of use
2. Performance
3. Detailed documentation

Source: State of API 2019 Report, SmartBear (2019)

@hvroussel @quod_ai
 Agenda?

1. What’s good API doc?

2. How can we create good API doc?
3. How do we keep it easy?

@hvroussel @quod_ai
 What do devs want?

Great API docs Excellent APIs docs

Interactive Authentication guide
Readable and consumable Quickstart guide
Easy to find and search Endpoint definitions What can I do?
API status page Code snippets
A changelog Example responses How can I do it?
Pricing

Source: Developer Portals with Great API Docs Pronovix (2018)

Source: 5 Examples of Excellent API Documentation Nordic APIs (2019)
@hvroussel @quod_ai
 How do devs search for code?
Find example code API consumer needs help
Find example code Discover correct library for task
Find example code Example to build off of
Find example code How to do something
Explore or read code Check implementation details
Explore or read code Browsing
Explore or read code Check best practices
Explore or read code Name completion
Find specific locations Trace through call graph
Find specific locations Sharing
Find specific locations Locations in source
Find specific locations Trace code history
Find specific locations Responsibility
Determine impact Why is something failing?
Determine impact Understanding dependencies
Determine impact Side effects of a proposed change

Source: How Developers Search for Code: A Case Study Google (2015)

@hvroussel @quod_ai
 How do devs search for code?
Find example code API consumer needs help
Find example code Discover correct library for task
Find example code Example to build off of
Find example code How to do something
Explore or read code Check implementation details
Explore or read code Browsing
Explore or read code Check best practices
Explore or read code Name completion What can I do?
Find specific locations Trace through call graph
Find specific locations Sharing
Find specific locations Locations in source How can I do it?
Find specific locations Trace code history
Find specific locations Responsibility
Determine impact Why is something failing?
Determine impact Understanding dependencies
Determine impact Side effects of a proposed change

Source: How Developers Search for Code: A Case Study Google (2015)

@hvroussel @quod_ai
 API docs don’t have to be complex

What can I do?

How can I do it?

Source: Stripe.com (2020)

@hvroussel @quod_ai
 Demo time

1. Introduction to APIs: Medium clone

2. Example API usage
3. Create awesome API docs with Quod AI
4. Run the code

@hvroussel @quod_ai
 What can I do?

How can I do it?

@hvroussel @quod_ai
 Thank you!

herve@quod.ai

Herve Roussel
Co-Founder at Quod AI

@hvroussel @quod_ai