Your SlideShare is downloading. ×
Developing documentation for RESTful APIs: how to kill three birds with one stone
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

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

1,312
views

Published on

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

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,312
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
2
Comments
1
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

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
  • 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. Tweaks: common output
  • 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. 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. Repository https://github.com/LoonyPandora/Pod -HTML5-Browser
  • 14. Thank you! Ilya Chesnokov <chesnokov.ilya@gmail.com>