The document discusses the importance of documentation for RESTful APIs for both users and developers, highlighting its role in code review and development. It introduces Perl's POD format as a user-friendly and extensible solution for creating API documentation, detailing how to read it and what content to include, such as API routes, input parameters, and output data. The author emphasizes that well-maintained documentation improves programming practices, eases testing, and eliminates the need for an admin panel by allowing use of an API console.

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>