Request examples are more than a mere addition to API documentation. They are necessary to easily onboard developers and increase API adoption. They cut development time by helping developers discover how to make a successful request to your API endpoints.
Imagine a Fintech API like Plaid without request examples in the API documentation. Their customer service will have to deal with complaints from frustrated developers each day. Eventually, developers will abandon their service for a better alternative.
My recent experience with The Movie Database (TMDB) API documentation underscores the importance of request examples in API documentation. It took me a couple of hours to figure out how to make a successful request to an endpoint because I couldn't access a request sample. However, I eventually found it in an unexpected place. ReadMe on the other hand didn't make it easy.
The Problem
Certain endpoints in the TMDB API require a RAW_BODY body parameter as seen in the image below:
Without a request sample, it is difficult to come up with the correct json data. Although, you may end up with a solution after a few google search, which is not a good user experience.
The solution
A glance at an endpoint page on ReadMe, there is no sight of a request sample. Despite being a very important part of API documentation, ReadMe didn't do a good job to make it easily accessible.
You can view a request sample for an endpoint on ReadMe through the steps below:
A. Click on the EXAMPLES field on the right and select the Request Example option.
B. The request sample will be displayed as seen in the image below:
That's all it takes to view a sample request in a ReadMe documentation.
NOTE: A request sample will be available provided that the API documentation writer(s) add it to the documentation.
Conclusion
This short article is useful for developers who may have to use an API with its documentation on ReadMe. If you also plan to use the TMDB API, this article will help you view sample request for each endpoint.
Top comments (0)