Developing documentation for RESTful APIs:
how to kill three birds
with one stone
Ilya Chesnokov
UK2 Group
Documentation is important
● for API users
– frontend developers
– customers using our API
– our techsupport and QA
● for ...
Perl - POD
● “Native” documentation format for Perl
● Easy to learn
● Simple to use
● Easily parseable
● Extensible (if yo...
How to read docs?
● perldoc
● unparsed source
● convert to HTML and read in a browser
How to read docs?
● perldoc
– programmers only!
● unparsed source
– programmers only!
● convert to HTML and read in a brow...
We need a converter!
What is documented?
● General description
● API routes and methods
● Input parameters
● Output data
– Possible errors
What is documented?
● General description =head1, =head2
● API routes and methods =head3
● Input parameters =head4, =item
...
=head3 POST /login
Loging using your credentials.
=head4 Input
=over
=item username
Username to login with.
=item password...
Tweaks: common output
=head3 ANY /domain/:domain
=head4 Output
...common output...
=head3 GET /domain/:domain
=for docviewer output-from ANY /do...
Results
● DDD FTW!
– documentation is always up to date
– good programming practice
● Testing (by hand) becomes even more ...
Repository
https://github.com/LoonyPandora/Pod
-HTML5-Browser
Thank you!
Ilya Chesnokov <chesnokov.ilya@gmail.com>
Developing documentation for RESTful APIs: how to kill three birds with one stone
Developing documentation for RESTful APIs: how to kill three birds with one stone
Developing documentation for RESTful APIs: how to kill three birds with one stone
Developing documentation for RESTful APIs: how to kill three birds with one stone
Developing documentation for RESTful APIs: how to kill three birds with one stone
Developing documentation for RESTful APIs: how to kill three birds with one stone
Upcoming SlideShare
Loading in …5
×

Developing documentation for RESTful APIs: how to kill three birds with one stone

1,734 views

Published on

This presentation is about a nice document viewer, which we use at UK2, developed by UK2 programmers.

Published in: Technology
1 Comment
1 Like
Statistics
Notes
No Downloads
Views
Total views
1,734
On SlideShare
0
From Embeds
0
Number of Embeds
10
Actions
Shares
0
Downloads
4
Comments
1
Likes
1
Embeds 0
No embeds

No notes for slide

Developing documentation for RESTful APIs: how to kill three birds with one stone

  1. 1. Developing documentation for RESTful APIs: how to kill three birds with one stone Ilya Chesnokov UK2 Group
  2. 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. 3. Perl - POD ● “Native” documentation format for Perl ● Easy to learn ● Simple to use ● Easily parseable ● Extensible (if you have fantasy)
  4. 4. How to read docs? ● perldoc ● unparsed source ● convert to HTML and read in a browser
  5. 5. How to read docs? ● perldoc – programmers only! ● unparsed source – programmers only! ● convert to HTML and read in a browser – everyone
  6. 6. We need a converter!
  7. 7. What is documented? ● General description ● API routes and methods ● Input parameters ● Output data – Possible errors
  8. 8. What is documented? ● General description =head1, =head2 ● API routes and methods =head3 ● Input parameters =head4, =item ● Output data =head4, =item – Possible errors
  9. 9. =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
  10. 10. Tweaks: common output
  11. 11. =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
  12. 12. 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
  13. 13. Repository https://github.com/LoonyPandora/Pod -HTML5-Browser
  14. 14. Thank you! Ilya Chesnokov <chesnokov.ilya@gmail.com>

×