REST API Style Guide

Terminology

• Resource - a noun that the API manages. Each resource has a URI in the API.
• Methods - One of the HTTP methods (GET, POST, PUT, etc.) that are applied to Resources.
• Headers - HTTP headers that are included in requests and responses.
• Status Codes - The numeric results on a method on a resource.
• Body Content - The representation of a resource at a URI. The content's format is specified by the MIME Type.
• Parameters - Parameters can be either in the path or in the URL query string.
• Representations - The serialization of some resource in a given format.

What does good API documentation look like?

A Simple Resource

The user resource describes an example user entity. A user resource looks like this when rendered as application/json:

{
  first: "Friedrich",
  last: "Strohmeyer",
  notes: ""
}

GET /example/users
> Accepts: application/json
< 200
< Content-Type: application/json
[
  { first: "Friedrich", last: "Strohmeyer", href="./1" },
  ...
]

GET /example/users/{id}
> Accepts: application/json
< 200
< Content-Type: application/json
{
  first: "Friedrich",
  last: "Strohmeyer",
  notes: ""
}

PUT /example/users/{id}
> Content-Type: application/json
{
  first: "Friedrich",
  last: "Strohmeyer",
  notes: "Discovered Cadmium in 1817."
}
< 204