DEV Community

Cover image for How to view API request examples in a ReadMe documentation.
Edun Rilwan
Edun Rilwan

Posted on • Edited on

1

How to view API request examples in a ReadMe documentation.

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.

PLAID API REQUEST EXAMPLE

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:

Raw body JSON parameter in the TMDB API

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:

  1. Click on the EXAMPLES field on the right and select the Request Example option. Image description
  2. The request sample will be displayed as seen in the image below:

Image description

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.

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay