The importance of the right ingredients for

your API documentation

“How to leave your customers without a bad taste in their mouths.”

@jkrggins#APIdays

Developer experience is the most important part of the API

economy• Designing an engaging

experience around your API.

• Managing the entire API lifecycle.

– IBM 2016

• With the popularity of microservices, developers are your decision makers. They will judge your API in a manner of seconds.

“My friend’s bakery burned down last night. Now his business is toast.”

Why API documentation IS

your business.

Devs eat documentation for

lunch

– ProgrammableWeb 2013

– James Yu, Parse

“The way to a developer’s heart is great documentation.”

“A good baker will always rise to the occasion, it’s the yeast he can do.”

Documentation-First: How to build an API for your consumer

– Garen Torikian, Github

“If I can’t describe it and I’m working

around something in the documentation,

then I need to fix something in the

code.”

Complicated documentation is a sign your code is too complicated.

– Rich Visotcky, agile coach

“Whenever we updated the method, the documentation port was right at the top. Our code we kept between two and 30 lines per

method. If they went much beyond that, they were breaking stuff down.”

In Scrum, “Documented” is the perfect definition of “Done.”

– Arnaud LauretAPI Handyman

“Even if you provide an internal API, you should create documentation, just like you do if you

sell it as a product. The people will consume it and use it.”

Documentation isn’t everything

1. Good documentation can’t fix a bad API. A lot of people fix bad APIs by just writing a lot of documentation.

2. A good API can’t be used without good documentation.

– Greg Koberger, ReadMe

Hello World:You have 3 minutes, 33 seconds

to sell your API

“A baker stopped making donuts after he got tired of the hole thing.”

The DX-journey begins with three questions

1. What does it take for them to be onboarded?

2. How do they get successful with the API?

3. How are they running their business with the API?

– Romain Huet, Stripe

3:30:3

30:3:30 Litmus Test• Understand in 3 seconds

what your API is for.

• Be able to identify the entry point in 30 seconds.

• Be able to create an account, call the system, and use the result in 3 minutes

– Ori Pekelman, Platform.sh

Never ever forget

• Authorization

• OAuth

• Terms & Conditions

– Bruno Pedro, Hitch

Which ingredients will make your API trés

magnifique?

“Bakers trade bread recipes on a knead to know basis.”

–“Winning the API Economy,” 3scale by Red Hat

“Excellent documentation also saves support effort and speeds the time it

takes customers to go live.”

Stop telling. Start showing!

• Copy-pastable code samples

• Then answer the following questions:What are the objects? Resources?What are the operations?What are perimeters?What’s the data in and out?Was it successful or not?

– Uri Sarid, MuleSoft

Set their expectations

• Call limits• Pricing• API error codes• Endpoints

Create great documentation or you

might as well not create an API at all.

“If you can’t take the heat, stay out of the kitchen.”

@jkrggins

#APIdays

Tweet a selfie with your copy to #APIdays and tell

us which influencer interviewed you trust the

most with your API advice.

“Crust me. I’m on a roll.”