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.

API Trace View

How I Cut 22.3 Seconds Off an API Call with Sentry

Struggling with slow API calls? Dan Mindru walks through how he used Sentry's new Trace View feature to shave off 22.3 seconds from an API call.

Get a practical walkthrough of how to identify bottlenecks, split tasks into multiple parallel tasks, identify slow AI model calls, and more.

Read more →

Top comments (0)

Billboard image

Try REST API Generation for Snowflake

DevOps for Private APIs. Automate the building, securing, and documenting of internal/private REST APIs with built-in enterprise security on bare-metal, VMs, or containers.

  • Auto-generated live APIs mapped from Snowflake database schema
  • Interactive Swagger API documentation
  • Scripting engine to customize your API
  • Built-in role-based access control

Learn more

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay