API Descriptions can be powerful design and implementation tools. In this session, we look at approaches to using API descriptions to create excellent API documentation, what kind of challenges you might encounter (technical as well as political), and some strategies to solve them. We'll talk about approaches to manage this information within your organization, as well as how to generate the best content with the least maintenance.

1. © Avalara
Translating and Testing your documentation
From API Description
to Developer Site
Anya Stettler
Defrag 2015

2. Making sales tax less taxing 2CONFIDENTIAL & PROPRIETARY |

3. Making sales tax less taxing 3CONFIDENTIAL & PROPRIETARY |

4. Making sales tax less taxing 4CONFIDENTIAL & PROPRIETARY |
https://stripe.com/docs/api#charges

5. Making sales tax less taxing 5CONFIDENTIAL & PROPRIETARY |
Policy AND Technology

6. Making sales tax less taxing 6CONFIDENTIAL & PROPRIETARY |

7. Making sales tax less taxing 7CONFIDENTIAL & PROPRIETARY |
…/v2/users
Vs
…/2.0/users
Consistency is key

8. Making sales tax less taxing 8CONFIDENTIAL & PROPRIETARY |
Not everything is worth fighting about

9. Making sales tax less taxing 9CONFIDENTIAL & PROPRIETARY |
Central dictionary for
shared vocabulary
We all need to speak the
same langauge

10. Making sales tax less taxing 10CONFIDENTIAL & PROPRIETARY |
Rules can’t stand alone

11. Making sales tax less taxing 11CONFIDENTIAL & PROPRIETARY |
More tools, less governance!

12. Making sales tax less taxing 12CONFIDENTIAL & PROPRIETARY |
The right way should be easy

13. Making sales tax less taxing 13CONFIDENTIAL & PROPRIETARY |
draft standards
draft standards
... in committee
create tools
management
management
management
Nag nag nag...
tool
maintenance
time saved
through
automation

14. Making sales tax less taxing 14CONFIDENTIAL & PROPRIETARY |
https://github.com/paypal/api-­standards/blob/master/api-­style-­guide.md

15. Making sales tax less taxing 15CONFIDENTIAL & PROPRIETARY |
Franchise!
-­‐ Value input
-­‐ Pilot program
-­‐ Transparent
feedback

16. Making sales tax less taxing 16CONFIDENTIAL & PROPRIETARY |
Guide lines road

17. Making sales tax less taxing 17CONFIDENTIAL & PROPRIETARY |

18. Making sales tax less taxing 18CONFIDENTIAL & PROPRIETARY |
http://swagger.io/

19. Making sales tax less taxing 19CONFIDENTIAL & PROPRIETARY |
?

20. Making sales tax less taxing 20CONFIDENTIAL & PROPRIETARY |
Is it valid Swagger?

21. Making sales tax less taxing 21CONFIDENTIAL & PROPRIETARY |
Vendor headers

22. Making sales tax less taxing 22CONFIDENTIAL & PROPRIETARY |
A single “source of truth” definition
Makes it easy for technical writers

23. Making sales tax less taxing 23CONFIDENTIAL & PROPRIETARY |
Swagger accurately reflects API?

24. Making sales tax less taxing 24CONFIDENTIAL & PROPRIETARY |
Follows company style guide?

25. Making sales tax less taxing 25CONFIDENTIAL & PROPRIETARY |

26. Making sales tax less taxing 26CONFIDENTIAL & PROPRIETARY |
We still need people!
• Human-­‐readable
property
definitions
• Define business
flows
• Describe best
practices

27. Making sales tax less taxing 27CONFIDENTIAL & PROPRIETARY |

28. Making sales tax less taxing 28CONFIDENTIAL & PROPRIETARY |

29. Making sales tax less taxing 29CONFIDENTIAL & PROPRIETARY |
2. https://upload.wikimedia.org/wikipedia/commons/a/af/Bedarra_Island_aerial.jpg
3. https://upload.wikimedia.org/wikipedia/commons/7/7e/Palau_archipelago.jpg
5. https://pixabay.com/p-­35105/
7. https://www.flickr.com/photos/nelsonminar/286841113
8. https://upload.wikimedia.org/wikipedia/commons/e/eb/Bicycle_shed.JPG
10. https://commons.wikimedia.org/wiki/File:United_States_Code_Law_Book_Boston_Public_Library_6D2B1951.jpg
11. https://www.flickr.com/photos/dominicotine/7696681446
12. https://c1.staticflickr.com/3/2451/3704243811_55b45a0fd0_b.jpg
15. https://commons.wikimedia.org/wiki/File:Dog_dressed_in_an_airplane_outfit.jpg
http://ichef-­1.bbci.co.uk/news/640/media/images/67206000/jpg/_67206577_de25.jpg
16. http://s3.freefoto.com/images/21/11/21_11_7_web.jpg
19. https://c2.staticflickr.com/4/3220/2936038678_06ae77a09d.jpg
https://www.flickr.com/photos/dapuglet/8479185386
https://c1.staticflickr.com/3/2792/4195466130_cdccf7f7c3_b.jpg
https://c1.staticflickr.com/3/2819/9190710208_cd972cd9c1.jpg
https://c1.staticflickr.com/1/2/1616041_2f42627c7b.jpg
https://pixabay.com/p-­309065/
20. https://www.flickr.com/photos/mbtrama/325408685
https://www.flickr.com/photos/8113246@N02/8203258965
23. https://www.flickr.com/photos/jurvetson/6877434491
25. https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/Sandro_Botticelli_-­_La_nascita_di_Venere_-­
_Google_Art_Project_-­_edited.jpg/1280px-­Sandro_Botticelli_-­_La_nascita_di_Venere_-­_Google_Art_Project_-­_edited.jpg
26. https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Quill_(PSF)_vector.svg/2000px-­
Quill_(PSF)_vector.svg.png
27. https://www.flickr.com/photos/portland_mike/969236814
Image Credits

30. Making sales tax less taxing 30CONFIDENTIAL & PROPRIETARY |
Thanks!
Anya Stettler
Product Manager, API
Avalara
anyarms
anya.stettler@avalara.com