Documenting your REST API

API.md

Title

<Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple).>

Method & URL

GET | POST | DELETE | PUT <The URL Structure (path only, no root url)>

<For Example: POST /api/search/fastsearch/>

URL Params

<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]

Data Params

<If making a post request, what should the body payload look like? URL Params rules apply here too. Please format code correctly>

Success Response

<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!>

• Status Code: 200

  {
    "hello": "world"
  }

Error Response

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

• Status Code: 401 UNAUTHORIZED

  { "error" : "Log in" }

• Status Code: 422 UNPROCESSABLE ENTRY

  { "error" : "Email Invalid" }

Sample Calls

<_Sample calls to your endpoint>

Notes

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