Writing Documentation for APIs
What Does Good API Documentation Contain? • • • • • • •
Sample of the code request Description and syntax of all operations Explanation of all parameters Sample of response Authorization issues Applicable API keys Possible error messages and troubleshooting
Google Maps Javascript API Documentation Example H T T P S : / / D E V E LO P E R S . G O O G L E . C O M / M A P S / D O C U M E N TAT I O N / J AVA S C R I P T / T U T O R I A L
( A LL S C R E ENSH OTS C OM E F R OM T H E LI NK A BOV E)
<!DOCTYPE html> <html> <head> <style type="text/css"> html, body { height: 100%; margin: 0; padding: 0; } #map { height: 100%; } </style> </head> <body> <div id="map"></div> <script type="text/javascript">
var map; function initMap() { map = new google.maps.Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 }); }
Start with a Simple Breakdown of the Sample Code Highlighting the Important Points
</script> <script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"> </script> </body> </html>
Then proceed to give a detailed explanation of each major point. • Include descriptions of the syntax. In this example, using <div> and <script> tags to contain the function. • Include every parameter. In this case, the two important parameters are center and zoom: function initMap() { map = new google.maps.Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 }); }
• Include use of API keys and Authorization options.
API Keys Unique String of Letters and Numbers • You request an API key from the site, such as YouTube, Twitter or Google.
• They look like this:
AIzaSyCdwEGYYCEf6THWteWEkd2YCokTyOTjLbM <script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"> </script>
API Keys and Documentation
FREE vs. FEES Always document this information near the beginning of the document!
Authorization
oauth.net
Great Examples of Well Documented APIs
youtube.com/yt/dev/
developers.google.com/
dev.twitter.com/overview/ documentation