RESTful API Documentation Template

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).>

• URL

  <The URL Structure (path only, no root url)>

• Method:

  <The request type>

  GET | POST | DELETE | PUT

• 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.>

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

  • Code: 200
    Content: { id : 12 }

• 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.>

  • Code: 401 UNAUTHORIZED
    Content: { error : "Log in" }

  OR

  • Code: 422 UNPROCESSABLE ENTRY
    Content: { 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.>

User.md

Show Single Account

Show a single Account if current User has access permissions to it.

URL : /api/accounts/:pk/

URL Parameters : pk=[integer] where pk is the ID of the Account on the server.

Method : GET

Auth required : YES

Permissions required :

User is at least one of the following in relation to the Account requested:

• Owner OO
• Admin AA
• Viewer VV

Data: {}

Success Response

Condition : If Account exists and Authorized User has required permissions.

Code : 200 OK

Content example

{
    "id": 345,
    "name": "Super Account",
    "enterprise": false,
    "url": "http://testserver/api/accounts/345/"
}

Error Responses

Condition : If Account does not exist with id of provided pk parameter.

Code : 404 NOT FOUND

Content : {}

Or

Condition : If Account exists but Authorized User does not have required permissions.

Code : 403 FORBIDDEN

Content :

{"detail": "You do not have permission to perform this action."}

Notes

There are security issues:

• This view allows existing users to test for existence of accounts that exist but that they do not have access to.
• Account IDs are sequential so an authorized user can count all the Accounts on the system.