Download as PDF, PPTX
Uploaded byWojtek Erbetowski
PyCon PL 2014 executable api
The presentation by Wojtek Erbetowski discusses the importance of good API documentation, highlighting the challenges of traditional documentation methods like wikis. It advocates for utilizing tools such as Swagger and APIary to create easily maintainable and up-to-date documentation, emphasizing that an API is only as effective as its documentation. The talk concludes with a focus on the balance between generated and design-first documentation approaches.
More Related Content
Similar to PyCon PL 2014 executable api
PyCon PL 2014 executable api
- 1. Good API documentationis executable Wojtek Erbetowski @erbetowski
- 2.
- 3.
- 4. Head of Engineeringat Polidea
- 5. Polidea is allabout mobile
- 6. What is thispresentation about? A little bit about why A little bit about why not More about how
- 7. Do you documentyour API? How many do not document? How many document on paper/wiki?
- 8. How is yourAPI documented? none/specs Wiki Other
- 9. Do you doWIKI? unhappy happy
- 10. Do you doWIKI? consumers providers
- 11. Simple and easy Easy to create/change Easy to modify by nontechnical
- 12. Not accurate! Easilygets out of sync You never know whether it’s you or them Not strict Often inconsistent
- 13. How to doit better?
- 14. What if ... … you had plenty of time and money?
- 15.
- 16.
- 17. Where’s the value? Easier to keep up-to-date Versioning Non-developers may read and maintain
- 18. Not only forbig players! RAML Swagger Apiary I/O Docs Apigee ...
- 20. Most popular tool Apiary Swagger RAML
- 21. “Give a manan API, and he APIs for a day. Teach a man to API, and he APIs for a lifetime.” Swagger
- 22. RAML API first Readability Mocking service
- 23. An API IsOnly As Good As Its Documentation Apiary
- 24. Comparison Swagger RAMLApiary Executable x x x API Platform x x Great UI x x Readability x x Easily generated x Scenarios x
- 25.
- 27.
- 28. Your docs canbe better! Get the best of two worlds: ● easy to keep up-to-date ● simple to create/edit
- 29. Start with Swagger simplest in configuration generates docs from current code
- 30. Big decision Generatedvs design first
- 31.
- 32. “I could generatedocs from existing app” about Swagger and Jersey
- 33. “It fails duringfunctional tests before we see it” about mocs generated from documentation
- 34. “It’s very hardto return ‘{}’ but how about ‘null’ ? ” how technology stack affects API design
- 35.
- 36.