Welcome to Volunteer Database’s documentation!

Contents:

API Documentation

Notation

Query Parameters

Validation

Query parameters which do not pass validation will be silently ignored.

Truthyness and Falsyness

For query parameters which expect a boolean, the following values are interpreted as True.

  • the string 'true'
  • the string 'True'
  • the number 1

For query parameters which expect a boolean, the following values are interpreted as False.

  • the string 'false'
  • the string 'False'
  • the number 0
  • the value null
Comparison notation

For query parameters which need comparisons beyond equality or truthyness, the following notation is used.

query_param integer size{__lt,__gt}:
 

In this example, the size query parameter can be sent in three formats.

  • /endpoint/?size=3

    All results with size equal to 3

  • /endpoint/?size__lt=3

    All results with size less than 3

  • /endpoint/?size__gt=3

    All results with size greater than 3

The following suffixes map to the followin comparisons.

  • __lt: <
  • __lt=: <=
  • __gt: >
  • __gte: >=
  • __ne: !=
  • __between l < x < r (non-inclusive of endpoints)
  • __ibetween l <= x <= r (inclusive of endpoints)
  • __lbetween l <= x < r (left inclusive of endpoints)
  • __rbetween l < x <= r (right inclusive of endpoints)

For between comparisons, the two values should be separated by a comma.

  • /endpoint/?size__between=1,8

    All sizes between 1 and 8,

Shifts

TODO: high level overview of the shift model.

Schema

TODO: specification for the shift schema and validation.

Endpoints

GET /api/v1/shifts/

The list view of all shifts.

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "next": "http://example.com/api/v1/shifts/?page=2"
  "prev": null,
  "count": 123,
  "results": [
    {
      "id": 1,
      ...
    },
    {
      "id": 2,
      ...
    },
    ...
  ]
}
Query Parameters:
 
  • page (integer) – Specify which page of results.
  • page_size (integer) – Page size for results. Max 100.
  • order (integer) – Sort the results. TODO: list choices.
  • shift_length{__lt,__lte,__gt,__gte,__between,__ibetween,__lbetween,__rbetween} (integer) – Filter to shifts based on their shift_length
  • start_time{__lt,__lte,__gt,__gte,__between,__ibetween,__lbetween,__rbetween} (datetime) – Filter to shifts based on their start_time
  • owner{__ne} (integer) – Filter to shifts based on the primary key of its owner.
  • department{__ne} (integer) – Filter to shifts based on the primary key of its department.
  • requires_code (boolean) – If True, only return shifts which require a code to claim. If False, only return shifts which do not require a code to claim.
Response JSON Object:
 
  • next (string) – The url of the next page of results. null if no next page.
  • prev (string) – The url of the previous page of results. null if no next page.
  • count (number) – The total number of records.
  • results (array) – The shift objects. See the detail view for the individual object schema.
Status Codes:
GET /api/v1/shifts/:id/

The detail view for a single shift.

Example response:

Content-Type: application/json

{
  "id": 1,
  ...
}
Response JSON Object:
 
  • id (number) – The primary key of the shift.

TODO: the rest of the schema

Status Codes:
PUT /api/v1/shifts/:id/

The detail view for a single shift.

Example request

Content-Type: application/json

{
  ...  # TODO
}

Example response

Content-Type: application/json

{
  "id": 1,
  ...  # TODO
}
Status Codes:
Response JSON Object:
 
  • department (integer) – The primary key of the Department the shift belongs to. Required.
  • start_time (datetime) – A datetime in ECMA 262 date time string specification. (Example 2013-01-29T12:34:56.123Z). All dates are in Mountain Time (UTC-0700).
  • shift_length (integer) – Number of hours in the shift. Must be greater than zero and less than or equal to 24 (0 < n <= 24). Requireds.
  • owner (integer) – The primary key of the User who has claimed the shift. Optional. Nullable.
  • code (string) – Code required to claim shift. Optional. If falsy, shift will not required a code. Nullable.
PATCH /api/v1/shifts/:id/

When making a PATCH request, only the fields that are posted are validated. This is useful for updating a single field, without caring what the other values need to be such as claiming a shift.

DELETE /api/v1/shifts/:id/

Delete the shift.

Status Codes:

Indices and tables