Tips for Documenting REST APIs

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:
   
   /widgets
   /widgets/:id
   /widgets?type=:type
   
   
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!