DutySheet API

The DutySheet API gives your access to a set of RESTful resources that you can use to retrieve data from DutySheet.

Please note that this documentation is in development and may not contain all the available references.

The base URL to access this API is:

https://api.dutysheet.com/api/

Any request sent to the DutySheet API must contain the Accept header with the corresponding version you would like to access.

Currently, the only available version is v2.

application/x.ds.v2+json

Most endpoints will require you to be authenticated using a JSON Web Token.

You must provide your JSON Web Token in the Authorization header in the following format:

Authorization: Bearer

In order to generate a JSON Web Token, you need to have an account set up on your DutySheet with the appropriate permissions and a API Password (please contact DutySheet support to generate a API password).

To generate a JSON Web Token, you need to send a POST request to /api/auth with your DutySheet username and API password.

Your JSON Web Token will expire after a set amount of time and you will no longer be able to access authenticated routes using the same token. You do not need to generate another JSON Web Token, instead, you can simple refresh your existing token using the /api/auth/refresh endpoint.

Here you can find common practices that can be found throughout the DutySheet API.

If the endpoint you are trying to request is authentication based, you must provide the Authorization header containing your JSON Web Token.

If your JSON Web Token expires while sending a request to an authenticated endpoint, you will receive a 401 unauthorized response from the API. You must refresh your JSON Web Token before trying to re-send your request.

The response you receive from an endpoint will change depending on the status of the request.

If a request is successful, most endpoint will respond with a key named data. The data key may be an object or array of resources depending on the context of the endpoint.

{
    "data": {
        "id": 1,
        "name": "Example"
    }
}

If there is an error during your request, the contents of the response will be different.

DutySheet API uses standard HTTP status codes to indicate the success or failure of the request. The body of the response will be standard throughout the API.

{
    "message": "404 Not Found",
    "status_code": 404
}

Some resources with large data sets may return the results using a paging mechanism. You can control the paging mechanism by providing different query string parameters.

You can change which page a paginated endpoint responds with by malipulating the page query parameter. You can also change how many items are in the response by updating the limit query parameter.

Below, you can find an example of what a paginated response will look like:

{
    "data": [
        {id: 1}, {id: 2}, {id: 3}, {id: 4}...
    ]
    "meta": {
        "pagination": {
            "total": 5664,
            "count": 15,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 378,
            "links": {
                "previous": "https://api.dutysheet.com/api/users?page=1",
                "next": "https://api.dutysheet.com/api/users?page=3"
            }
        }
    }
}

Most resources will have additional data that can be included in the response if your request it.

The include query parameter accepts a comma separated string of resources that you would like to include.

For example, the /users endpoint will only include limited details by default. You can then include additional information by adding the include query parameter to the request.

https://api.dutysheet.com/api/users?include=rank,division,borough,station

Endpoints relating to listing, viewing and updating user details.

All endpoints that list a user have available includes that you can use to retrieve additional information.

The following includes are available:

• rank

• division

• borough

• station

• contactDetails

• textFields

• dropdowns

• dates

• certifications

• emergencyContacts

• supervisor

Endpoints relating to listing, viewing and updating duties.

All endpoints that list a duty have available includes that you can use to retrieve additional information.

The following includes are available:

• user (and all user includes)

• division

• borough

• station

• type

• role

Endpoints relating to listing divisions

All endpoints that list a division have available includes that you can use to retrieve additional information.

The following includes are available:

• boroughs

Endpoints relating to listing boroughs

All endpoints that list a borough have available includes that you can use to retrieve additional information.

The following includes are available:

• stations

Endpoints relating to listing stations