Over a million developers have joined DZone.

Tips for Documenting REST APIs

DZone's Guide to

Tips for Documenting REST APIs

Like any piece of software, documentation is critical to its uptake and success. This more so the case when you want your own REST API to be understood and used with as little interaction from the original developers as possible. Here are some tips to help make that happen.

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

Image title

Having a REST API available to interact with your system can be a great asset, and can help get more and more developers to use your service. However, incomplete or hard-to-read documentation for your API can make it difficult for people to make use of it. Therfore, good documentation is a must if you want to get as many people up and running with your API as possible. So, what are some things that can be done?

Include as Much Helpful Information as Possible

This probably goes without saying, but you can help developers immensely by providing helpful, straightforward information that lets people know what to expect when they make an API call. For example, here are some key pieces of information you may wish to include in your documentation:

  1. Title: It is a good idea to lead with a meaningful title that describes the action that will be taken. Leading with the URL can be confusing, as it is less likely to convey the action to be taken quickly. For example, a title could be “Get all widgets” or “Post new message."

  2. URL: List the path that will be used to make a call. Variable parameters are signified by a colon. Some examples:


  3. Request type: Be sure to include what type of request needs to be made – GET, POST, PUT or DELETE.

  4. Parameters: Include any parameters that are available, and whether each is required or optional.

  5. Expected responses: What responses should the user expect on success or failure? For example, the API might return 200 on success or 401 if the request is unauthorized.

Of course, these are just the basics. You may wish to add special notes or provide examples of what will be posted or returned for each route, all of which will prove helpful for developers making use of your API!

Be Consistent

In addition to providing the right information, it is a good idea to be consistent in its presentation. Be sure to use a consistent template for displaying the documentation for each route (commonly a layout that looks visually like a table). Also, use consistent naming conventions.

For example, try to avoid using two terms that refer to the same thing, such as using the terms “users” and “members” to refer to the users of the system. If they are two different entities in your system, then be sure to make the distinction clear in your documentation, as it will help avoid confusion and make your API easier to use!

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

rest api ,rest ,api ,documentation ,tips

Published at DZone with permission of JohnPollock, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.


Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.


{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}