Documenting your REST API

API.md

Hint: This is heavily based on https://gist.github.com/3428555.

Api Name

Title: METHOD URL

Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple). The request type and the URL Structure (path only, no root url). METHOD may be GET | POST | DELETE | PUT.

URL Parameters

If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required. Document data constraints.

Required

• id integer

Optional

• photo_id alphanumeric

Payload Data

If making a post request, what should the body payload look like? URL Params rules apply here too.

Success Response: 200 OK

What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!

{"id": 12}

Error Response: 401 UNAUTHORIZED

Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be listed here. It might seem repetitive, but it helps prevent assumptions from being made where they should be.

{"error": "Log in"}

Error Response: 422 UNPROCESSABLE ENTRY

It might seem repetitive, but it helps prevent assumptions from being made where they should be.

{"error": "Email Invalid" }

Sample Call

Just a sample call to your endpoint in a runnable format ($.ajax call or a curl request) - this makes life easier and more predictable.

Notes

This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.

EXAMPLE.md

User Api

Show User: GET /users/:id

Returns json data about a single user.

URL Parameters

Required:

• id integer

Payload Data

None

Success Response: 200 OK

{"id": 12, "name": "Michael Bloom"} 

Error Response: 404 Not Found

{"error": "User doesn't exist" }

Error Response: 401 UNAUTHORIZED

{"error" : "You are unauthorized to make this request."}

Sample Call

  $.ajax({
    url: "/users/1",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });