APIs define contracts between a service and a client, and with the rise of representation languages like Swagger, Apiary, and RAML, these contracts can be consumed programmatically and adapted easily into our codebases. Other tools like JSON Schema also contribute to this idea of integration between service and client. But what about our documentation? If API contracts can be assimilated into software, surely it can drive our documentation too? In this talk, I want to introduce some of the techniques I've used on past projects that allow exactly that. By using remote schemas to generate software, it also allows us to generate working documentation that is always relevant and never out of date. Apart from accuracy, we also get the added benefits of reduced development time, reduced effort, and reduced duplication. We can all of this by documenting once, and re-using across multiple projects!

1. Generating docs
from APIs
Prague, 2015
@jamiehannaford

2. 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?

3. Some assumptions
• Very basic knowledge of HTTP/REST
• Familiarity with JSON
• A love of cats (all will be explained...)

4. 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.

5. 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

6. Implementing APIs in Flask

7. Does it work?!

8. How do we structure resource
data?

10. 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.

11. Making sense of our
JSON blob

12. "colour" property

13. "name" property

14. "status" property

15. "toys" property

17. 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.

18. But it's not enough...

19. 3 popular solutions
Swagger RAML API blueprint
apiblueprint.orgraml.orgswagger.io

20. Hierarchical paths

21. Operation parameters

22. Generate docs

23. Documenting parameters

24. Sandbox

25. Generating clients

26. 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?

27. Thank you!
(Děkuji!)
Slides available later
@jamiehannaford