Documenting REST APIs
Download as PPTX, PDF3 likes2,774 views
The document outlines a course on documenting REST APIs, emphasizing the importance of complete and accurate documentation for API technical writers. It covers various aspects of REST APIs including understanding requests and responses, utilizing tools like curl and Postman, and the essential sections needed in API documentation such as resource descriptions, endpoints, parameters, and sample requests and responses. Additionally, it provides guidance on creating user guides and proper formatting for documentation aimed at developers.
![1.7 ANALYZE THE JSON
RESPONSE
JSON arrays are lists of items:
["first", "second", "third"]
Arrays start and end with square brackets [ ].](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-37-320.jpg)
![1.7 ANALYZE THE JSON
RESPONSE
An array can contain a list of objects:
[
{
"name":"Tom",
"age":39
},
{
"name":"Shannon",
"age":37
}
]](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-38-320.jpg)
![1.7 ANALYZE THE JSON
RESPONSE
An object can contain arrays:
children: ["Avery","Callie","lucy","Molly"],
hobbies:
["swimming","biking","drawing","horseplaying
"]](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-39-320.jpg)
![1.9 ACCESS THE VALUES
FROM JSON
Use square brackets to access the values in an array:
"data" : {
"items": ["ball", "bat", "glove"]
}
To access glove, you would use data.items[2]](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-46-320.jpg)
![1.9 ACCESS THE VALUES
FROM JSON
Download the dotnotationexercise.html file from the
workshop files.
Change john.children[0].child1 to display the
following:
• green
• nike
• goldenrod
• Sarah](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-47-320.jpg)
![2.4 DOCUMENTING SAMPLE
REQUESTS
The sample request clarifies how to use the endpoint
http://api.nytimes.com/svc/search/v2/article
search.response-format?[q=search
term&fq=filter-field:(filter-
term)&additional-params=values]&api-key=####](https://image.slidesharecdn.com/workshoprestcourse-150624090853-lva1-app6891/85/Documenting-REST-APIs-68-320.jpg)
Documenting REST APIs
- 1. DOCUMENTING REST APIS BY TOM JOHNSON IDRATHERBEWRITING.COM STC Summit 2015 Columbus, Ohio @tomjohnson
- 2. CONVENTIONS • Access the course module at http://idratherberwriting.com/restapicourse • 1.1 Numbers in slide headings refers to the place in the course module. • This icon indicates an activity you’re supposed to do. • If you get lost, read the course page.
- 3. 1.0 OVERVIEW • Focus of the course is REST APIs • Time to completion • Learn with a real example and context • No programming skills required
- 4. 1.0 OVERVIEW What you’ll need: • Text editor • Chrome browser • Postman REST Client • cURL • Network connection Follow along online: idratherbewriting.com/restapicourse
- 5. 1.1 INTRODUCTION TO REST API DOCUMENTATION Complete and accurate docs are most important factor in APIs
- 6. 1.1 INTRODUCTION TO REST API DOCUMENTATION REST APIs are taking off in a huge way
- 7. 1.1 INTRODUCTION TO REST API DOCUMENTATION Job market is hot for API technical writers
- 8. 1.1 INTRODUCTION TO REST API DOCUMENTATION API doc is a new world for most tech writers
- 9. 1.1 INTRODUCTION TO REST API DOCUMENTATION Increasing learning materials about API documentation
- 10. 1.2 USING A REST API LIKE A DEVELOPER An API is an interface between systems.
- 11. 1.2 USING A REST API LIKE A DEVELOPER Our course scenario: Weather forecast API
- 12. 1.2 USING A REST API LIKE A DEVELOPER Get an idea of the end goal
- 13. 1.2 USING A REST API LIKE A DEVELOPER Browse the available APIs on Mashape
- 14. 1.2 USING A REST API LIKE A DEVELOPER Find the "Weather" API by fyhao
- 15. 1.2 USING A REST API LIKE A DEVELOPER Answer some questions about the API • What does the API do? • How many endpoints does the API have? • What does each endpoint do? • What kind of parameters does each endpoint take? • What kind of response does the endpoint provide? ✔ Terminology tip: API == Endpoint
- 16. 1.3 GET THE AUTHORIZATION KEYS • Authorization for making API calls • License access to the API • Rate limit the number of requests • Control availability of certain features within the API
- 17. 1.3 GET THE AUTHORIZATION KEYS Get the Mashape authorization keys
- 18. 1.3 GET THE AUTHORIZATION KEYS To get the keys: 1. Click Sign Up Free and create an account. 2. Click Applications on the top nav bar. 3. Click Get the Key. 4. In the dialog box, click Copy. (Choose the Testing keys.) 5. Open up a text editor and paste the key.
- 19. 1.3 GET THE AUTHORIZATION KEYS Text editors: • Sublime Text (Mac or PC) • TextWrangler (Mac) • WebStorm (Mac or PC) • Notepad++ (PC)
- 20. 1.4 MAKE A CURL CALL Prepare the cURL call: 1. Go into Weather API. 2. Copy the cURL request example for the aqi endpoint into your text editor. 3. Important: If you're on Windows, change the single quotes to double, and add -k as well to work around security certificate issues. 4. Swap in your own API key. 5. Use Google Maps to find the latitude and longtitude of your current location.
- 21. 1.4 MAKE A CURL CALL Make the call in cURL (Mac) 1. Open a terminal. 2. Paste the call you have in your text editor into the command line. 3. Press your Enter key.
- 22. 1.4 MAKE A CURL CALL Make the call in cURL (Windows) 1. Copy the cURL call from your text editor. 2. Go to Start and type cmd to open up the command line. 3. Right-click and then select Paste to insert the call.
- 23. 1.4 MAKE A CURL CALL If it didn’t work, try the Advanced REST Client
- 24. • cURL is a cross-platform way to show requests and responses • REST APIs follow the same request/return model of the web • Try using cURL to GET a web page: curl http://example.com 1.5 UNDERSTANDING CURL
- 25. Requests and responses include headers too Use –i or -I include the response header: curl http://example.com -i curl http://example.com -I 1.5 UNDERSTANDING CURL
- 26. Other methods you can use besides GET: • POST: Create a resource • GET: Read a resource • PUT: Update a resource • DELETE: Delete a resource 1.5 UNDERSTANDING CURL
- 27. 1.5 UNDERSTANDING CURL Specifying the method with a cURL call --get -X GET -x PUT curl –X GET http://example.com
- 28. 1.5 UNDERSTANDING CURL Passing headers into the request: -H curl --get --include 'https://simple- weather.p.mashape.com/aqi?lat=37.354108&lng= -121.955236’ -H 'X-Mashape-Key: WOyzMuE8c9mshcofZaBke3kw7lMtp1HjVGAjsndqIPbU 9n2eET' -H 'Accept: text/plain'
- 29. 1.5 UNDERSTANDING CURL Passing data into the request: -d curl -i -H "Accept: application/json" -X POST -d "{status:MIA}" http://personsreport.com?status
- 30. 1.5 UNDERSTANDING CURL Make cURL more readable: curl -i -H "Accept: application/json" -X POST -d "{status:MIA}" http://personsreport.com?status
- 31. 1.5 UNDERSTANDING CURL Query strings: ?lat=37.354108&lng=-121.955236 Listening multiple parameters: ¶meter1¶meter2¶meter3
- 32. 1.6 SUBMIT REST CALLS THROUGH POSTMAN GUI clients make REST calls a little easier Common GUI clients: • Postman • Advanced REST Client • Paw
- 33. 1.6 SUBMIT REST CALLS THROUGH POSTMAN Insert the cURL call into Postman following the sample screenshot
- 34. 1.6 SUBMIT REST CALLS THROUGH POSTMAN View the format of the weatherdata response in pretty JSON
- 35. 1.7 ANALYZE THE JSON RESPONSE Prettify the JSON response: http://jsonformatter.curiousconcept.com/ JSON is how most REST APIs structure the response
- 36. 1.7 ANALYZE THE JSON RESPONSE JSON objects are key-value pairs: { "key1":"value1", "key2":"value2" } JSON objects start and end with curly braces { }.
- 37. 1.7 ANALYZE THE JSON RESPONSE JSON arrays are lists of items: ["first", "second", "third"] Arrays start and end with square brackets [ ].
- 38. 1.7 ANALYZE THE JSON RESPONSE An array can contain a list of objects: [ { "name":"Tom", "age":39 }, { "name":"Shannon", "age":37 } ]
- 39. 1.7 ANALYZE THE JSON RESPONSE An object can contain arrays: children: ["Avery","Callie","lucy","Molly"], hobbies: ["swimming","biking","drawing","horseplaying "]
- 40. 1.7 ANALYZE THE JSON RESPONSE Identify the objects and arrays in the weatherdata API response. • Where are the objects? • Where are the arrays?
- 41. 1.8 LOG THE JSON RESPONSE TO THE CONSOLE Making use of the JSON response Use the sample code from Mashape to parse and display the REST response: http://docs.mashape.com/javascript
- 42. 1.8 LOG THE JSON RESPONSE TO THE CONSOLE Customize the Mashape code with the weatherdata endpoint: 1. Open text editor. Insert Mashape code. 2. Customize the url to the useweatherdata endpoint. 3. Enter your API key. 4. Uncomment out the next to console.log(data). 5. Save and view the file in Chrome. 6. Open the Developer Console: View > Developer > JavaScript Console. Refresh page.
- 43. 1.8 LOG THE JSON RESPONSE TO THE CONSOLE You can customize your Console log messages Inspect the payload Replace "undefined”: document.getElementById("output").innerHTML = data.query.results.channel.item.description;
- 44. 1.9 ACCESS THE VALUES FROM JSON Dot notation allows you to access specific values from the JSON response data.query.results.channel.item.description
- 45. 1.9 ACCESS THE VALUES FROM JSON How dot notation works "data": { "name": "Tom" } To access Tom, I would use data.name.
- 46. 1.9 ACCESS THE VALUES FROM JSON Use square brackets to access the values in an array: "data" : { "items": ["ball", "bat", "glove"] } To access glove, you would use data.items[2]
- 47. 1.9 ACCESS THE VALUES FROM JSON Download the dotnotationexercise.html file from the workshop files. Change john.children[0].child1 to display the following: • green • nike • goldenrod • Sarah
- 48. 1.9 ACCESS THE VALUES FROM JSON Get the wind speed from the weather API weatherdata endpoint. Download the windcalls.html file from the workshop files. Look at the different values accessed from the JSON response.
- 49. 2.0 YOU HAVE A NEW API TO DOCUMENT Shift perspectives: Now you're the technical writer You have a new endpoint to document Review the wiki page: http://idratherbewriting.com/restapicourse2-0/
- 50. 2.0 YOU HAVE A NEW API TO DOCUMENT Essential sections in REST API documentation: • Resource description • Endpoint • Methods • Parameters • Request submission example • Request response example • Status and error codes • Code samples
- 51. 2.0 YOU HAVE A NEW API TO DOCUMENT Create the basic structure for the endpoint documentation Use a text editor to create the sections. Bonus: Use Markdown syntax.
- 52. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION The terminology to describe a "resource" varies: • API calls • Endpoints • API methods • Calls • Resources • Objects • Services • Requests
- 53. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION Look at some examples: • Mailchimp • Twitter • Instagram
- 54. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION Referring to resources by the endpoint name can get problematic: api_site.com/{apikey}/users // gets all users api_site.com/{apikey}/users/{userId} // gets a specific user api_site.com/{apikey}/rewards // gets all rewards api_site.com/{apikey}/rewards/{rewardId} // gets a specific reward api_site.com/{apikey}/users/{userId}/rewards // gets all rewards for a specific user api_site.com/{apikey}/users/{userId}/rewards/{rewardId} // gets a specific reward for a specific user api_site.com/{apikey}/users/{userId}/rewards/{missionId} // gets the rewards for a specfic mission related to a specific user api_site.com/{apikey}/missions/{missionid}/rewards // gets the rewards available for a specific mission
- 55. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION One resource can have multiple endpoints
- 56. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION When describing the resource, start with a verb. Review some examples: • Delicious API • Foursquare API • Box API
- 57. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION Review the surf report wiki page (2.0) containing the information about the endpoint, and try to describe the endpoint in the length of one or two sentences.
- 58. 2.1 DOCUMENTING THE RESOURCE DESCRIPTION • Critique the Mashape Weather API descriptions • There’s a difference between reference docs versus user guides • Re-using the resource description
- 59. 2.2 DOCUMENTING THE ENDPOINT DEF. AND METHOD Terminology for the endpoint definition varies: • Requests • Endpoints • API methods • Resource URIs • Resource URLs • URLs • URL syntax
- 60. 2.2 DOCUMENTING THE ENDPOINT DEF. AND METHOD The endpoint definition usually contains the end path only /surfreport/{beachId} Represent parameter values with curly braces
- 61. 2.2 DOCUMENTING THE ENDPOINT DEF. AND METHOD You can list the method beside the endpoint
- 62. 2.2 DOCUMENTING THE ENDPOINT DEF. AND METHOD • Write the endpoint definition for surfreport • Aim for 1-3 sentences
- 63. 2.3 DOCUMENTING PARAMETERS Parameters are ways to configure the endpoint
- 64. 2.3 DOCUMENTING PARAMETERS Data types indicate the format for the values: • String • Integer • boolean
- 65. 2.3 DOCUMENTING PARAMETERS • Parameter order doesn’t matter /surfreport/{beachID}?days=3&units=metric&ti me=1400 • Note any max and min values • Note whether parameters are optional or required
- 66. 2.3 DOCUMENTING PARAMETERS • You can also pass parameters in the JSON body { "days": 2, "units": "imperial", "time": 1433524597 } • Time values usually follow ISO or Unix format
- 67. 2.3 DOCUMENTING PARAMETERS Construct a table to list the surfreport parameters
- 68. 2.4 DOCUMENTING SAMPLE REQUESTS The sample request clarifies how to use the endpoint http://api.nytimes.com/svc/search/v2/article search.response-format?[q=search term&fq=filter-field:(filter- term)&additional-params=values]&api-key=####
- 69. 2.4 DOCUMENTING SAMPLE REQUESTS API Explorers provide interactivity with your own data
- 70. 2.4 DOCUMENTING SAMPLE REQUESTS API Explorers can be dangerous in the hands of a newbie
- 71. 2.4 DOCUMENTING SAMPLE REQUESTS • If different requests return different responses, show multiple responses Document the sample request with the surfreport/{beachId} endpoint
- 72. 2.5 DOCUMENTING SAMPLE RESPONSES • Provide a sample response for the endpoint • Example from Flattr API • Define what the values mean in the endpoint response
- 73. 2.5 DOCUMENTING SAMPLE RESPONSES Strategies for documenting nested objects Check out the following approaches: • Dropbox • Bit.ly • eBay
- 74. 2.5 DOCUMENTING SAMPLE RESPONSES Information design choice: Where to include the response
- 75. 2.5 DOCUMENTING SAMPLE RESPONSES • Use realistic values in the response • Format the JSON in a readable way • Add syntax highlighting • Some APIs embed dynamic responses
- 76. 2.5 DOCUMENTING SAMPLE RESPONSES Create a section for a sample request in your surfreport/{beachId} endpoint
- 77. 2.6 DOCUMENTING RESPONSE AND ERROR CODES • Response codes let you know the status of the request • Common status codes follow standard protocols: http://www.restapitutorial.com/httpstatuscodes.html
- 78. 2.6 DOCUMENTING RESPONSE AND ERROR CODES • List the HTTP response and error codes • Main page and also on each endpoint where relevant
- 79. 2.6 DOCUMENTING RESPONSE AND ERROR CODES Run your request and look at your header code List three status codes for surfreport/{beachId}
- 80. 2.7 DOCUMENTING CODE SAMPLES IN REST APIS • Code samples bridge the gap between reference and user guides • Look at the code sample on Mashape: http://docs.mashape.com/javascript • Code samples are like candy for developers
- 81. 2.7 DOCUMENTING CODE SAMPLES IN REST APIS • You are not the audience • Focus on the why, not the what • Focus on the why, not the what • Focus your explanation on your company's code only
- 82. 2.7 DOCUMENTING CODE SAMPLES IN REST APIS • Keep code samples simple • Add both code comments and before-and-after explanations • Make code samples copy-and-pastable
- 83. 2.7 DOCUMENTING CODE SAMPLES IN REST APIS Provide a code sample in your target language
- 84. 2.7 DOCUMENTING CODE SAMPLES IN REST APIS • From code samples to real tasks in user guides • Your turn to practice: Create a code sample and documentation for the surfreport endpoint
- 85. 2.8 PUTTING IT ALL TOGETHER • View my sample here: http://idratherbewriting.com/restapicourse2-8/ • Share and comment on each other’s samples?
- 86. 2.9 CREATING THE USER GUIDE User guides versus reference documentation Essential sections in a user guide: • Overview • Getting started • Authorization keys • Core concepts • Rate limits • Code samples • Hello world tutorial • Quick reference • Glossary
- 87. 2.9 CREATING THE USER GUIDE Overview section
- 88. 2.9 CREATING THE USER GUIDE Getting started section
- 89. 2.9 CREATING THE USER GUIDE Authorization keys
- 90. 2.9 CREATING THE USER GUIDE Rate limits
- 91. 2.9 CREATING THE USER GUIDE Quick reference guide
- 92. 3.0 COMPLETION Learning summary • How to make calls to an API using cURL and Postman • How to pass parameters to API calls • How to inspect the objects in the JSON payload • How to use dot notation to access the JSON values you want • How to display the integrate the information into your site
- 93. 3.0 COMPLETION Learning summary • Documenting the resource description • Documenting the endpoint definition and method • Documenting parameters • Documenting the request example • Documenting the response example • Providing a code example • Listing status codes
- 95. IMAGE CREDITS Most images are screenshots linked to a webpage, but some are from Flickr. Required attribution is as follows: • Structure, https://flic.kr/p/oFD6MM Rafal Zych • Earth patterns. https://flic.kr/p/ssQqiL Evriel Venefice • Dave’s Bike Tools, https://flic.kr/p/QMVMw Bri Pettis