Building Better APIs: Documentation

An API is only as good as its documentation. This presentation covers a few best practices that can help overcome common challenges when building APIs. It also provides an overview of helpful tools for building better API documentation – API Blueprint (including MSON), Dredd, and Apiary.

Accompanying post: https://medium.com/@galenandrew/building-better-apis-documentation-8c29e06d6463

Transcript

1. Building Better APIs: Documentation API Blueprint – Dredd – Apiary
2. An API is only as good as its documentation.
3. Common Challenges
4. No Documentation
5. Disparate Documentation and Functionality
6. Development is blocked by API readiness
7. Not knowing what/when API changed
8. Documentation First Approach Think of it like TDD for APIs
9. Slow down; plan your API
10. Write good documentation
11. Test code against documentation
12. Provide mocks for Developers
13. Tools
14. API Blueprint Documentation Syntax
16. MSON Markdown Syntax for Object Notation
18. JSON MSON
20. Dredd API Testing Utility $ dredd ./apiary.apib 'http://localhost:3000'
21. Apiary Hosted Documentation, Mock Server, Test/Traffic Inspector
25. Demo
26. Resources
27. API Blueprint
 https://apiblueprint.org Dredd
 http://dredd.rtfd.org Apiary
 https://apiary.io Slides
 https://speakerdeck.com/galenandrew/building-better-apis Example Documentation
 http://docs.dialexastarterapi.apiary.io General
28. API Blueprint Examples
 https://github.com/apiaryio/api-blueprint/tree/master/examples MSON Tutorial
 https://apiblueprint.org/documentation/mson/tutorial.html MSON Examples
 https://github.com/apiaryio/mson/tree/master/examples API Blueprint
29. Hooks
 https://dredd.readthedocs.io/en/latest/hooks/ Response 204 Bug
 https://github.com/apiaryio/dredd/issues/468#issuecomment-218130203 Dredd
30. Apiary CLI
 https://help.apiary.io/tools/apiary-cli/ Enhancing Apiary Workflow
 https://help.apiary.io/api_101/enhancing-apiary-workflow/ Apiary
31. Thank you!