REST API Documentation - A First Guideline

If you develop a API, specially a REST API, you have to assure that it is documented well. There is no uniquely accepted way to formalize RESTful services. Nevertheless you want attract third-party developer and make the API use as easy as possible.

The Quickstart

Nothing is so great as to begin fast with the use of an API. For this purpose the documentation website should provide a few, simple step how to start.

The Detailed Description

The following things are a must for each API documentation:

• HTTP method and URL, e.g. GET /crises
• Supported formats, e.g. JSON, JSONP, RDF
• Supported parameters. Outline clearly which parameters are required and which are optional and what is the semantic behind this parameters.
• Example call: How does a concrete call with parameters and the response HTTP header look like, e.g. by the use of curl
• Output: The data that is returned. Possible as concrete instance, e.g. JSON example output, or as UML class diagram.
• Link to more help: You can for example link the creation of a new question at StackOverflow.com

Additional Resources

The Code

It is really helpful for developer do look into example code. You can use for this for example gitorious.org, github.com, bitbucket.org or any other hosting service that makes forking easy.

The Example Client

Additional to the source code it is also helpful to have a running instance of this code. That simplifies the understanding and allows the developer to test the client without the need to setup it up. This is only possible if the client is a web application.

Annotation

I have come up with this guideline during the development for the Sigimera REST API (see http://api.sigimera.org). The API is not finished, neither this guideline, but it should help to remember the essential points for the documentation.

Please let me know if I have forgotten something.