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: - 200 OK – success.
- 403 Forbidden – permissions error.
- 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: - 200 OK – success.
- 404 Not Found – not found.
- 403 Forbidden – permissions error.
- 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: - 200 OK – success.
- 404 Not Found – not found.
- 403 Forbidden – permissions error.
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: - 204 No Content – success.
- 404 Not Found – not found.
- 403 Forbidden – permissions error.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\