Welcome to the documentation for Cerulean's REST API! The REST API is open for everyone to use and write their own custom clients if you feel that our clients are inadequate! We also maintain this documentation to help ease the development of our own clients. This documentation is kept in-tree and updated with the latest commit so that you can go through git history for older versions. Report any issues with the documentation here.
This REST API is still a work in progress! Some endpoints and features have not been finalised. If you are writing a Cerulean client, you will need to keep track of the current API until beta versions are released. Additionally, some of these endpoints have not yet been implemented in the back-end.
POST /todos/order- Repeated todo items API is WIP.
POST /registeremail verification.POST /resendverifyemailPOST /forgotpasswordPOST /verifyuser
All dates sent to and fro from the REST API are encoded as ISO 8601 strings as emitted by Date#toISOString in JavaScript. All request and response bodies, if present, are formatted in JSON.
For authentication, the Cerulean REST API requires an Authorization header or a cerulean_token cookie to be sent with every request, containing a token which is sent to the client after logging in using the POST /login endpoint. The POST /logout endpoint can be used to invalidate the user's token. The token returned expires after 6 months. Your client should be well equipped to handle token expiries.
The user's password can be changed using the POST /changepassword endpoint. The minimum password length is 8 characters for security reasons. Calling this endpoint logs the user out everywhere except their current session. A user can be registered using the POST /register endpoint, after which they will be sent an email containing a link to a webpage with a token in the query string, which upon loading will call POST /verifyuser to activate the account with the token in the query string. This token has an expiry date of 24 hours, and can be resent by calling POST /resendverifyemail.
The user's account can be deleted with POST /deleteaccount. This deletion is permanent, and cannot be undone. Hence, this endpoint should be treated with caution.
If you are writing a client, and your client goes offline, there are 2 ways to ensure that your client can continue to work offline without messing up any data on the back-end that may be more up to date. It is highly advisable to follow these guidelines. One way to cache all todos on the client, and display them in a read-only mode until an internet connection is available again. However, this is not an ideal user experience.
The ideal way is to cache the todos on the client and create an array of todo IDs which your local client has deleted. When you reconnect to the back-end, you must call the GET /todos endpoint to get the latest todos from the server. You can then compare this with your own cache by taking the response, deleting todos from it that your client deleted, modifying todos sharing the same ID in your local cache and the response, and adding todos present in your cache which are not present on the server. Additionally, you can compare the order of the local cache and server response and calculate an appropriate order for the merged lists. Once you have done the comparison, you can send the required DELETE/PATCH/POST requests to the server to sync your local cache with the server, and then overwrite your local cache with GET /todos.
We may eventually provide a POST /sync endpoint, which would take all todos on the client as well as the client's old cache, merge them with the back-end's copy, and send back a merged list of todos to the client. This would reduce the amount of client-side logic and provide resistance against network failures, which may cause unexpected behaviour.
Each endpoint may return certain errors, which have been documented in the description for their response. In addition to the documented errors, every endpoint could return a 5xx HTTP error code which should be handled correctly by the client, and 405 Method Not Allowed and 400 Bad Request if the client is sending invalid requests which do not comply with the parameters. Apart from /login and /register, all endpoints require the cerulean_token cookie (set by /login if cookie query param is not false) or an Authorization header, containing a valid session access token, else you will receive 401 Unauthorized.
When there is an error, the server will reply with an object containing error, a string with an error message in English (UK). This message is intended to be shown directly to the user. We will eventually add a code or lang field to the response with corresponding documentation for proper i18n support.
Register a new Cerulean account. Bienvenue !
| Name | Type | In | Description |
|---|---|---|---|
username |
string | body | A username (a-zA-Z0-9_) to register with, not already used, of length 4-16. |
email |
string | body | A valid email to register with, not already registered. |
password |
string | body | The password to register with. Minimum length: 8. |
cookie |
boolean | query | Optional: Set to false to avoid getting Set-Cookie: cerulean_token= |
Possible errors include 409 Conflict if someone has an account with the existing username and email, and 400 Bad Request if the username, email or password fail validation.
{"token":"JRPnrZPzeb8hi+RigUYZjIBWg4N1hImlI+AwKkfi4fk"}Log into the Cerulean API and retrieve a token.
| Name | Type | In | Description |
|---|---|---|---|
username |
string | body | The username to login with. |
password |
string | body | The password to login with. |
cookie |
boolean | query | Optional: Set to false to avoid getting Set-Cookie: cerulean_token= |
Possible errors include 401 Unauthorized if your username or password is invalid.
{"token":"JRPnrZPzeb8hi+RigUYZjIBWg4N1hImlI+AwKkfi4fk"}Logout and invaliate the current token.
| Name | Type | In | Description |
|---|---|---|---|
| N/A |
{"success":true}Change your current user's password. This also invalidates all tokens except your current one.
| Name | Type | In | Description |
|---|---|---|---|
currentPassword |
string | body | The old password. |
newPassword |
string | body | The new password you wish to set. Minimum length: 8 |
Possible errors include 400 Bad Request if your new password is less than 8 characters and 401 Unauthorized if the provided current password is incorrect.
{"success":true}Delete your account. Au revoir. This is irreversible and logs you out. If writing a client, make sure to cover any calls to this with a big warning dialog.
| Name | Type | In | Description |
|---|---|---|---|
| N/A |
{"success":true}Get all of the user's todo items. Read the parameters for POST /todo to help understand the response of this endpoint fully. id, createdAt and updatedAt are created by the server and cannot be edited directly.
| Name | Type | In | Description |
|---|---|---|---|
| N/A |
{
"todos": [
{
"id": "507f191e810c19729de860ea",
"name": "Buy milk",
"description": "Buy milk",
"done": false,
"repeating": "daily",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
},
{
"id": "507f1f77bcf86cd799439011",
"name": "Call Anna",
"done": false,
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
},
{
"id": "54495ad94c934721ede76d90",
"name": "Review notes",
"description": "Check for grammatical errors",
"done": true,
"dueDate": "2016-01-02T00:00:00Z",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
}
]
}Create a new todo item for the current user.
| Name | Type | In | Description |
|---|---|---|---|
| name | string | body | The todo name. |
| done | boolean | body | Optional: If the todo is done or not. |
| description | string | body | Optional: The todo description. |
| dueDate | date | body | Optional: The todo's due date. |
| repeating | string | body | Optional: The todo is repeating. Enum of "daily", "weekly", "monthly", "yearly". |
Possible errors include 400 Bad Request if your todo does not include a name or if the dueDate is incorrectly formatted.
{
"id": "507f191e810c19729de860ea",
"name": "Buy milk",
"description": "Buy milk",
"done": false,
"repeating": "daily",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
}Get one of the user's todo items. Read the parameters for POST /todo to help understand the response of this endpoint fully. id, createdAt and updatedAt are created by the server and cannot be edited directly.
| Name | Type | In | Description |
|---|---|---|---|
| id | string | path | The ID of the todo item to get. |
Possible errors include 404 Not Found if a todo with the given ID doesn't exist.
{
"id": "507f191e810c19729de860ea",
"name": "Buy milk",
"description": "Buy milk",
"done": false,
"repeating": "daily",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
}Edit one of the user's todo items. Read the parameters for POST /todo to help understand the response of this endpoint fully. id, createdAt and updatedAt are created by the server and cannot be edited directly.
| Name | Type | In | Description |
|---|---|---|---|
| id | string | path | The ID of the todo item to edit. |
| name | string | body | Optional: The todo name. |
| done | boolean | body | Optional: Whether the todo is done or not. |
| description | string | body | Optional: The todo description. |
| repeating | string | body | Optional: The todo is repeating. Enum of "daily", "weekly", "monthly", "yearly". |
| dueDate | date | body | Optional: The todo's due date. |
Possible errors include 404 Not Found if a todo with the given ID doesn't exist and 400 Bad Request if the dueDate is incorrectly formatted.
{
"id": "507f191e810c19729de860ea",
"name": "Buy milk",
"description": "Buy milk",
"done": false,
"repeating": "daily",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
}Note: The endpoint returns the updated todo item.
Delete one of the user's todo items. Read the parameters for POST /todo to help understand the response of this endpoint fully. id, createdAt and updatedAt are created by the server and cannot be edited directly.
| Name | Type | In | Description |
|---|---|---|---|
| id | string | path | The ID of the todo item to get. |
Possible errors include 404 Not Found if a todo with the given ID doesn't exist.
{
"id": "507f191e810c19729de860ea",
"name": "Buy milk",
"description": "Buy milk",
"done": false,
"repeating": "daily",
"createdAt": "2016-01-01T00:00:00Z",
"updatedAt": "2016-01-01T00:00:00Z"
}