1. Introduction

A good way to start when building (or trying to repair) an RESTful API is to either find a well documented standard that you like or write your own standard document based on other peoples experience. The most imporant thing is that you settle for a standard that makes all your API resources consistent and easy to work with.

2. API design resources

3. API documentation resources

API Blueprint is a trending format for documenting APIs. It is a format that is similar to markdown and is friendly both to humans and machines.

One piece of advice is to keep the documentation close to the code. Our approach is to have the documentation in the same version control repository as the code base for the API. This will make sure that the documentation is synchronized with the code.