API Documentation Guidelines

Properly documenting an API's end points is just as important as writing the code that builds it. Documentation is generally stored in the README.md file in at the base of your repo, and is written using Markdown formatting. You can get a feel for the formatting used by viewing any README.md file as raw (click the "Raw" button in GitHub)—including this one. Good documentation:

Formatting

The following examples serve to illustrate a pattern for formatting documentation for a CRUD endpoint.

  1. Begin with the method name—GET, POST, PUT, PATCH, or DELETE—followed by the endpoint's URL.
  2. For endpoints that accept input via a JSON-formatted request body, show an example in a Body section, followed by a Notes section with specifics about data formats.
    • GET endpoints that accept optional query parameters can skip the Body and list them in the Notes section.
  3. The Response section should show a sample of a valid JSON response body.
  4. Finally, list the possible Status Codes, especially paying attention to 4xx codes and their meaning.

Add a new building

POST: /api/building

Body:

{
    "name": "Super Cool Building",
    "latitude": 41.893740,
    "longitude": -87.635330
}

Notes:

Response:

{
    "id": "7032AC0B-BE6D-4873-81B7-7BFD91BFD5F0",
    "name": "Super Cool Building",
    "latitude": 41.893740,
    "longitude": -87.635330
}

Status Codes:

Get a list of buildings

GET: /api/building

Notes: An optional latitude and longitude can be supplied as query parameters to narrow the results within a two mile radius.

Response:

{
    "count": 24,
    "next": "http://blahblahblah.com/api/building?page=2",
    "previous": null,
    "results": [
        {
            "id": "7032AC0B-BE6D-4873-81B7-7BFD91BFD5F0",
            "name": "Super Cool Building",
            "latitude": 41.893740,
            "longitude": -87.635330
        },
        ...
    ]
}

Status Codes:

Get a single building

GET: /api/building/:id

Response:

{
    "id": "7032AC0B-BE6D-4873-81B7-7BFD91BFD5F0",
    "name": "Super Cool Building",
    "latitude": 41.893740,
    "longitude": -87.635330
}

Status Codes:

Update a building

PATCH: /api/building/:id

Body:

{
    "name": "New Building Name",
    "latitude": 51.5033630,
    "longitude": -0.1276250
}

Notes:

Response:

{
    "id": "7032AC0B-BE6D-4873-81B7-7BFD91BFD5F0",
    "name": "New Building Name",
    "latitude": 51.5033630,
    "longitude": -0.1276250
}

Status Codes:

Delete a building

DELETE: /api/building/:id

Response: None

Status Codes:

Bitmasks

Option sets that are expected to contain more than ~3 items can be stored and transported more efficiently using a bitmask. Keep to these standards to avoid any ambiguity about bit order. Specify when a bit becomes unused. Use no more than 32 bits.

For Example:

Starting from the least significant bit these flags are available:

Default settings: 20 (10100 with least significant bit on right)

DateTimes

All datetimes sent and received by the API should conform to RFC 3339 Internet timestamp standard. For example: 2015-04-16T13:34:22.023000Z.

In Python use the formatting string '%Y-%m-%dT%H:%M:%S.%fZ'. Go can use time.RFC3339. Enforcing the setting in Django Rest Framework is detailed in the DRF standards doc.