Developing documentation for RESTful APIs

Or how to kill three birds with one stone

Transcript

1. Developing documentation for RESTful APIs: how to kill three birds with one stone Ilya Chesnokov UK2 Group
2. Documentation is important • for API users – frontend developers – customers using our API – our techsupport and QA • for API developers – code review – further use, development and refactoring of API – documentation (design)-driven development
3. Perl - POD • “Native” documentation format for Perl • Easy to learn • Simple to use • Easily parseable • Extensible (if you have fantasy)
4. How to read docs? • perldoc • unparsed source • convert to HTML and read in a browser
5. How to read docs? • perldoc – programmers only! • unparsed source – programmers only! • convert to HTML and read in a browser – everyone
6. We need a converter!
7. What is documented? • General description • API routes and methods • Input parameters • Output data – Possible errors
8. What is documented? • General description =head1, =head2 • API routes and methods =head3 • Input parameters =head4, =item • Output data =head4, =item – Possible errors
10. =head3 POST /login Loging using your credentials. =head4 Input =over =item username Username to login with. =item password Password to login with. =back =head4 Output ... The POD
15. Tweaks: common output
17. =head3 ANY /domain/:domain =head4 Output ...common output... =head3 GET /domain/:domain =for docviewer output-from ANY /domain/:domain =head4 Output ...specific output ... Common output
18. Results • DDD FTW! – documentation is always up to date – good programming practice • Testing (by hand) becomes even more easy • No need to write an admin panel – people use API console instead
19. Repository https://github.com/LoonyPandora/Pod -HTML5-Browser
20. Thank you! Ilya Chesnokov <chesnokov.ilya@gmail.com>