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 of your API can make it difficult for people to make use of the API, so 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!

SaaS with Morpheus

Do you need to deploy APIs, apps, databases, and other infrastructure quickly? Try out Morpheus, which provides Software as a Service with excellent flexibility.

The Morpheus interface is clean and easy to use. Source: Morpheus.

Morpheus allows you to provision apps in a single click, and provides ease of use for developers with APIs and a CLI. In addition, backups are also automatic, and you can have redundancy as needed to avoid potentially long waits for disaster recovery to take place. So, why not register an account or sign up for a Morpheus demo today?