Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Building Better APIs: Documentation

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


Andrew Turner

May 11, 2016


  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

  15. None
  16. MSON Markdown Syntax for Object Notation

  17. None

  19. None
  20. Dredd API Testing Utility $ dredd ./apiary.apib 'http://localhost:3000'

  21. Apiary Hosted Documentation, Mock Server, Test/Traffic Inspector

  22. None
  23. None
  24. None
  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

 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

    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!