A Documentation Model for a RESTful API

In this article, I propose a documentation structure for RESTful Web Services.

RESTful Web Services lack any standard for modeling. By that I mean, the URI syntax, HTTP method, response code etc. are all left up to the API designer. Without a clear documentation, developers can be left guessing about exactly how to invoke a service. There is a reason good documentation is considered a key best practice in a RESTful API design.

I have seen pretty messy documentation, some from fairly well known companies. Don’t let that happen to you.

What Needs to be Documented?

There are some factors that are common to all entry points or operations of the service. They need to be documented in one place:

  1. The base URL consisting of the protocol and host name only.
  2. Any details about the authentication scheme.

For each entry point (or operation) supported by the API, document these items.


  1. What does the operation do?
  2. What are the security requirements? Is SSL or authentication required?

For the request:

  1. The HTTP method.
  2. URI syntax. This may contain the base URL for ease of use.
  3. URL parameters if any.
  4. Request body parameters if any.
  5. Supported MIME types (Content-type request header).

For the response:

  1. Meaning of various HTTP reply codes.
  2. Schema of the response body in success situation.
  3. Schema of the response body in error situations.

The URI Syntax

URI is used to uniquely identify a resource or a specific collection of resources. It should be documented using place holder parameters. Example:




Name Type Description
productId Integer The ID of the product

URL Parameters

URL parameters are normally used with GET requests only. They provide filtering and sorting criteria. They should be documented using place holder parameters.


Name Type Description
sortBy String How to sort the results. Possible values: PRICE, ALPHABATIC. Optional. Default is PRICE.
maxSize Integer Maximum number of products returned. Optional. Default is 100.

Request Body Parameters

Request Body Parameters

Request body is normally used with PUT and POST requests. They are listed in a table similar to the URL parameters.

Describing the Response Body Schema

Most APIs use examples to describe the schema. This is not a bad way. For XML response, it may be useful to also attach a schema document.

Example Case Study

Get a Product



Name Type Description
productId Integer The ID of the product

HTTP Method: GET

URL Parameters

Name Type Description
lang String The language code in which the description of the product will be returned. Possible values en, fr and es. Optional. Defaults to browser’s language setting.
currency String Currency in which prices are returned. Possible values USD, CAD and EUR. Optional. Default is USD.

MIME Types

text/xml, application/xml and application/json

HTTP Reply Codes

Code Meaning
200 Success
404 Product not found. Check the ID.
500 Invalid language or currency setting.

Response Body on Success


  <name>Baseball gloves</name>


  “id”: 1001,
  “price”: 172.00,
  “currency”: “USD”,
  “image”: “http://images.example.com/small/1001.png&#8221;,

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s