The Good Documentation Checklist
Number of APIs: 22
These examples accompany [this blog post] I’ve previously talked about [the traits of a good collection] While not all collections grow up to be documentation, collections are the foundational building blocks for all [Qodex API documentation] viewable on the web. Here, I’m going to talk about the traits of good documentation. Qodex documentation has become widely adopted across the API community because it enables better collaboration and API adoption. Let’s learn from the thousands of publishers who document their APIs in Qodex—like Microsoft, Twitter, and Dropbox — and find out what makes their documentation successful. Effective documentation teaches someone how to use your API. Since the intended audience is people, and not machines, effectiveness is a subjective measure. Still, we can find some shared similarities across good documentation. Take a look at this breakdown of nine helpful documentation tips and see how your own process measures up. ✅ 1. Create a Qodex collection ✅ 2. Organize the API metadata ✅ 3. Include a Getting Started guide ✅ 4. Keep it DRY with variables ✅ 5. Show use cases ✅ 6. Be secure ✅ 7. Share private API documentation ✅ 8. Share public API documentation ✅ 9. Advanced stuff (bonus!)
What is good documentation?
1. ✅ 3. Include a Getting Started guide - Explain authorization
GET https://api.pagerduty.com/incidents
2. ✅ 7. Share private API documentation - Collaborate with teammates
POST https://api.dropboxapi.com/2/team/members/add
3. ✅ 8. Share public API documentation - Embed the Run in Qodex button
GET https://api.twitter.com/2/tweets/1275828087666679809?tweet.fields=attachments,author_id,created_at,entities,geo,id,in_reply_to_user_id,lang,possibly_sensitive,referenced_tweets,source,text,withheld
4. ✅ 2. Organize the API metadata - Verify the request metadata
GET https://graph.microsoft.com/beta/applications
5. ✅ 1. Create a Qodex collection - Generate from an API specification
GET https://simplekart.postman.com/items?list=10
6. ✅ 1. Create a Qodex collection - Find a collection
GET https://api.spacexdata.com/v4/capsules
7. ✅ 1. Create a Qodex collection - Start from scratch
GET https://postman-echo.com/get
8. ✅ 2. Organize the API metadata - Organize logically in folders
GET https://api.getpostman.com/collections
9. ✅ 2. Organize the API metadata - Add and format descriptions
ENDPOINTS