APIs

Note: This documentation is preliminary and requires more formalization. An OpenAPI document will eventually be provided.

All REST endpoints are provided under /api/v1.

Common datatypes

UUIDs are represented with their canonical form in a string. Serial numbers are represented as a decimal number, optionally in a string (to avoid issues with JavaScript Number accuracies).

Binary data is represented in Base64 wherever plausible (except UUIDs).

A list entry is represented as:

{
	"id": "Serial number for the entry ID",
	"ciphertext": "Base64-encoded ciphertext of the list entry",
	"nonce": "Base64-encoded Nonce for encryption of the ciphertext"
}

/user/login

APIs related to user login. Rate limited to ~5 requests per endpoint, username, and minute.

GET /user/login/salt?username=<username>

Request the salt for a user account. Yields 403 if the user does not exist (or for rate limiting, to not leak information).

{
	"salt": "<base64 encoded salt>"
}

GET /user/login

Requests a session token for a user account. The Authorization header must contain the username and HA password hash. Unsuccessful authentications return 403 (whether user exists or not).

{
	"session-token": "<base64 encoded token>"
}

The access token is added to the site cookies by JavaScript (using the Set-Cookie header is unnecessarily convoluted thanks to CORS).

/user/register

Create a new user account. (TODO)

DELETE /user

Delete a user account. (TODO)

/user/list

Manage a user’s saved lists. Get all lists (GET), which returns a JSON array.

A user’s lists are represented as:

{
	"id": "<UUID of the list>",
	"elk": "<base64 encrypted list key>",
	"token": "<access token UUID if present>"
}

For single lists (/user/list/<list uuid>): get a list (GET), add a list (POST), delete a list (DELETE).

/list/<list uuid>

Retrieve a list’s data in JSON form (GET), update a list’s data (POST), delete a list (DELETE).

The response to the GET request is:

{
	"id": "<list id>",
	"title": "<base64 encoded encrypted list title, optional>",
	"nonce": "<base64 encoded title nonce, optional>",
	"entries": [
		// <array of all items>
	]
}

An update (POST) is presented in the following form:

{
    "title": "<base64 encoded, encrypted new or changed list title>",
    "nonce": "<title nonce, required if title is changed or now>",
    "add": [
        // <items that should be added, without IDs, so only ciphertext-nonce pairs>
    ...],
    "modify": [
        // <items that should be modified>
    ...],
    "delete": ["<list of deleted ids>", ...]
}

Any top-level key may be omitted to not submit updates of this type.

/list/<list uuid>/permissions

Manage permissions for a list. (TODO)

POST /list/new

Create a new list, no body required. The server responds with:

{
	"id": "<uuid of the new list>"
}