Backend API

Backend API Documentation

All of the backend API code is contained within the api/ folder.

Authentication

All authentication code is contained within auth.js. All API endpoints support both session-based authentication and sessionless (token-based) authentication.

Session-based authentication is done by sending a POST request containing credentials to the /api/login endpoint. Clients can authenticate through one of several methods:

• By POSTing a JSON object with username and password fields
• By POSTing URL encoded form data (media type application/x-www-form-urlencoded) with username and password fields.
• Using basic HTTP authentication (i.e. an Authorization header).

The server will reply with a user object containing information about who was just logged in, as well as a session cookie. This cookie must be sent for all further API requests.

A login session can be ended by sending a GET request to /api/logout.

All API endpoints additionally support sessionless / token-based authentication, using basic HTTP authentication: simply send an Authentication header alongside your requests.

Users

Get information on a user

Get information on the currently authenticated user (available to non-admins):

GET /api/user

Get information on any user (admin-only):

GET /api/users/:uid

Example Response:

Status: 200 OK

{
    "id": "596c0f93f5ef262d1cabd479",
    "username": "tester",
    "realname": "Tester Tester",
    "admin": false,
    "disabled": false,
    "created": "2017-07-18T18:04:45.111Z",
    "updated": "2017-07-17T01:14:59.204Z"
}

---

Change a user's password

Change the currently authenticated user's password (available to all users):

POST /api/user/password

Change any user's password (available to administrators only):

POST /api/users/:uid/password

Parameters

Parameter	Type	Description
password	string	The new password for the user.

Response

Status: 204 No Content

Note that this will cause a logout, if using session-based authentication and changing one's own password.

---

Get details on all users

GET /api/users

This endpoint does not require administrator privileges to access, unlike every other endpoint under /api/users.

Example Response

Status: 200 OK

[
    {
        "id": "596bfa3b243de52b388607b1",
        "username": "admin",
        "realname": "Initial User",
        "admin": true,
        "disabled": false,
        "created": "2017-07-17T00:22:44.754Z",
        "updated": "2017-07-16T23:43:55.046Z"
    },
    {
        "id": "596c0f93f5ef262d1cabd479",
        "username": "tester",
        "realname": "Tester Tester",
        "admin": false,
        "disabled": false,
        "created": "2017-08-26T00:19:21.259Z",
        "updated": "2017-07-17T01:14:59.204Z"
    }
]

---

Create a new user

POST /api/users

Parameters

Parameter	Type	Description
username	string	The name to use for authentication / login.
realname	string	A real-world identifier to associate with this user.
password	string	The user's password for authentication.
admin	boolean	Whether or not this user should have administrator privileges.
disabled	boolean	Whether or not authentication should be disabled for this user.

Example Response

Status: 201 Created

{
    "id": "59a0c329e8a6aa1018b03541",
    "username": "Tester",
    "realname": "Tester Tester",
    "admin": false,
    "disabled": false,
    "created": "2017-08-26T00:39:05.208Z",
    "updated": "2017-08-26T00:39:05.208Z"
}

---

Modify a single user's details

PUT /api/users/:uid

Parameters

Parameter	Type	Description
:uid	string	The user ID
username	string	The name to use for authentication / login.
realname	string	A real-world identifier to associate with this user.
admin	boolean	Whether or not this user should have administrator privileges.
disabled	boolean	Whether or not authentication should be disabled for this user.

Example Response

Status: 200 OK

{
    "id": "596c0f93f5ef262d1cabd479",
    "username": "tester",
    "realname": "Tester Tester",
    "admin": false,
    "disabled": false,
    "created": "2017-07-17T01:14:59.204Z",
    "updated": "2017-08-26T00:28:36.711Z"
}

---

Delete a user

DELETE /api/users/:uid

Parameters

• uid [string, in URL]: The user ID

Response

Status: 204 No Content

Inventory and Item Types

TODO: see inventory.js

Get inventory item information

Get information on all items:

GET /api/inventory

Get information on a specific item:

GET /api/inventory/:item_id

Response

This method returns an Item object.

Create a new item:

POST /api/inventory

Parameters

Parameters	Type	Description
name	string	Name of item type
count	integer	Initial total inventory count

Update an item's info:

PUT /api/inventory/:item_id

Parameters

Parameters	Type	Description
name	string	Name of item type
count	integer	Initial total inventory count

Delete an item:

DELETE /api/inventory/:item_id

Get an item type's reservations:

GET /api/inventory/:item_id/reservations

Reservations

TODO: see reservations.js

Get reservation info

Get info on all reservations:

GET /api/reservations

Get info on a single reservation:

GET /api/reservations/:reservation_id

Create and Update reservations

Create a new reservation:

POST /api/reservations

Update a reservation:

PUT /api/reservations/:reservation_id

Parameters

Parameters	Type	Description
part	Item ID	ID of item to reserve.
count	integer	Number of units of item to reserve.
requester	User ID	ID of user making reservation.
username	string	Name of user making reservation; requester parameter takes priority over this if present.