Generating docs from APIs

Prague, 2015 @jamiehannaford

What are we going to talk about today?

• What are some of the problems surrounding developing and documenting APIs?

• How can we centralise the information we produce? Is DRY docs feasible?

• How can we improve communication and team dynamics?

• How can we streamline production and save time?

Some assumptions

• Very basic knowledge of HTTP/REST

• Familiarity with JSON

• A love of cats (all will be explained...)

What is a web API?• An interface that allows users to perform tasks.

• A contract between server and client. Specifies exactly how something can be executed.

• "Defines functionalities that are independent of their respective implementations."

• Documentation is tasked with communicating this API contract in a simple, effective way.

Adopt-a-cat API

• Cat has an ID, name, colour, adoption status, and a selection of favourite toys.

• List all cats

• Retrieve details about a specific cat

• Create a new cat

Implementing APIs in Flask

Does it work?!

How do we structure resource data?

What is JSON Schema?• A way of modelling an API resource, like a cat, in

JSON. What properties does it have? What are their types? How would you describe them?

• Keywords allow us to add meaning and contextualise arbitrary blobs of JSON.

• Allows us to translate our assumptions into a consistent format for users to consume.

Making sense of our JSON blob

"colour" property

"name" property

"status" property

"toys" property

What does it offer us?

• Centralise representation data of our models.

• Free from implementation details.

• Standardised, consistent validation.

• A human- and machine-readable document to share with users.

But it's not enough...

3 popular solutions

Swagger RAML API blueprint

apiblueprint.orgraml.orgswagger.io

Hierarchical paths

Operation parameters

Generate docs

Documenting parameters

Sandbox

Generating clients

Wrap-up

• What are some of the problems we experience?

• Projects that can help us: Swagger, RAML, Apiary.

• Define once, re-use everywhere. Forgo the normal problems of duplication and knowledge gaps.

• Why be excited about them?

Thank you! (Děkuji!)

Slides available later @jamiehannaford