Activity: Critique or create an API reference topic
After completing the API reference tutorial, you’re ready to start an activity that gives you more experience in creating and editing API reference documentation. In this activity, you’ll either critique or create your own API reference topic for the open-source API project you identified earlier.
- Critique the API reference documentation
- Create or fix an API reference documentation topic
- Next steps
Critique the API reference documentation
If you’ve found an open source project, great. If you don’t have a project but you still want to do the activity, select one of the API from the list of 100 API doc sites here.
To critique an API reference topic:
- Locate one of the reference topics for a resource in the API.
Identify each of the sections in the existing documentation:
- Resource description
- Request example
- Response example and schema
The section names may differ, but they usually are easily recognizable.
Evaluate each of these sections and assess whether the documentation is complete. Are there areas for improvement? Critique one or more of the API reference topics.
Here are some questions to look at:
Resource description: Is the description action-oriented? Is it a brief 1-3 sentence summary? Is it clear? Does it link to more information somewhere else?
Endpoints and methods: Does the endpoint list the methods available? Are any path parameters in the endpoint easy to identify? If there are multiple endpoints, are they logically grouped?
Parameters: Is each parameter described? Are the parameters separated out into different sections by parameter type? If it’s a request body parameter, are the data types indicated? Are max and min values identified? Any unsupported values noted?
Request example: Does the sample request work (with the right authorization)? Does it include a representative number of parameters? Is it formatted correctly in curl? Are any other languages shown with the sample request? Is the code syntax highlighted?
Response example: Does the sample response match the sample request? Is it formatted and highlighted correctly? Is each element in the response described, along with the data type? Does the response documentation separate the example from the description, or combine the two? How are nested objects portrayed? Are any status and error codes listed?
Create or fix an API reference documentation topic
This part of the activity might be more difficult to do, but here is where you’ll start building some examples for your portfolio.
- Identify one of the API reference topics that needs help. (If the API has a new reference endpoint to document, focus on this endpoint.)
- Edit the topic to improve it. (If it’s a new endpoint, write the documentation for it.)
- Create a pull request and contribute your edits to the project.
Now that you’ve had your head buried in API reference documentation, it’s time to dive into testing a bit more. As you work with API endpoints and other code, you’ll need to test these endpoints yourself, both to gather and verify the information in your documentation. Testing isn’t always straightforward, so I devote an entire section to this topic. Continue to Overview to testing your docs.
32/107 pages complete. Only 75 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.