- Настройка базы данных
- Регистрация пользователя
- Вход пользователя в аккаунт и получение токена
- Получение списка досок пользователя
- Создание доски
- Получение доски
- Изменение доски
- Удаление доски
- Создание карточки
- Изменение карточки
- Удаление карточки
- Создание задачи
- Теги
- Временные рамки
- Изменение задачи
- Удаление задачи
- Редактирование временных рамок задачи
- Создание подзадачи
- Изменение подзадачи
- Удаление подзадачи
- Редактирование временных рамок подзадачи
- Получение тегов
- Создание тегов
- Изменение тегов
- Удаление тегов
В целом, работа с API выглядит следующим образом:
- Пользователь регистрируется и/или получает новый токен.
- Пользователь отправляет запросы с этим токеном.
Сервер умеет манипулировать такими сущностями, как Board, Card, Task, Subtask, Tag, Timeline и другими (см. model.rs и auth.rs).
В некоторых методах, которые создают сущность из запроса клиента и возвращают клиенту идентификатор этой сущности в базе данных, можно передавать любой id в сущности, так как он, очевидно, будет переназначен. В методах же, которые редактируют сущности, большинство параметров являются необязательными для отправки, и, например, если мы хотим поменять в подзадаче только цвет фона, то параметры цвета текста, заголовок задачи, исполнителей и отметку о выполнении отправлять не нужно.
Настройка базы данных в целом проводится единожды, создавая в PostgreSQL четыре таблицы. Но метод может создавать только те таблицы, которые отсутствуют в базе данных, и если вы удалили несколько, вызов этого метода повлечёт создание этих таблиц.
GET /pg-setup
Для работы метода необходимо передать заголовок App-Token
, содержащий закодированный в base64 JSON:
{
"key": "<Ключ администратора>"
}
Метод возвращает код 200 в случае успеха и может возвращать коды 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
Регистрация пользователя необходима для работы в приложении CC TaskBoard. Аккаунт даёт возможность получать доступ к доскам и создавать свои.
PUT /sign-up
Для работы метода необходимо передать заголовок App-Token
, содержащий закодированный в base64 JSON:
{
"login": "<Логин>",
"pass": "<Пароль длиной не менее 8 символов>",
}
В случае успеха метод возвращает код 200 и передаёт в теле ответа токен, который необходимо передавать каждый раз в заголовке App-Token
для аутентификации действий пользователя:
{
"id": 1234567890,
"token": "<Токен>"
}
Токен валиден в течение 5 дней, которые не использовался.
Помимо этого, метод может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
Вход в аккаунт необходим для получения пользователем токена. Он используется для аутентификации вместо логина и пароля.
GET /sign-in
Для работы метода необходимо передать заголовок App-Token
, содержащий закодированный в base64 JSON:
{
"login": "<Логин>",
"pass": "<Пароль>"
}
В случае успеха метод возвращает код 200 и передаёт в теле ответа токен, который, предварительно закодировав в base64, необходимо будет передавать каждый раз в заголовке App-Token
для аутентификации действий пользователя:
{
"id": 1234567890,
"token": "<Токен>"
}
Токен валиден в течение 5 дней, которые не использовался.
Помимо этого, метод может возвращать коды 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
GET /list
Для работы метода необходимо передать токен в заголовке App-Token
.
Метод возвращает статус 200 и JSON-массив с данными о доске (id
, title
, header_background_color
и header_text_color
), либо ошибки 401 и 500.
Доска - главный объект в CC TaskBoard. Она содержит карточки с задачами и подзадачами и может быть доступна тем пользователям, с которым ею поделились. Пользователи не имеют права редактировать доску, в отличие от содержимого внутри, которое было также создано ими.
PUT /board
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"id": 0,
"author": 0,
"shared_with": [],
"header": {
"title": "<Заголовок доски>",
"header_background_color": "#<Цвет RRGGBB>",
"header_text_color": "#<Цвет RRGGBB>",
},
"cards": [],
"background": {
"color": "#<Цвет RRGGBB>"
}
}
Передача различных значений в полях id и author не имеет смысла, так как сервер игнорирует их. Например, владелец токена становится владельцем доски, и его id из токена записывается в поле author. Идентификатор доски генерируется базой данных.
Для использования какого-либо изображения в качестве фонового для доски укажите этот параметр следующим образом:
{
"background": {
"url": "<Картинка на удалённом ресурсе>"
}
}
Передача одного или нескольких id в списке shared_with и карточек в cards также смысла не имеет.
В случае успеха метод возвращает код 200 и передаёт в теле ответа идентификатор доски. Помимо этого, метод может возвращать коды 400, 401, 402, 500 в случае ошибки. Текст ошибки передаётся в теле.
Всё содержимое доски можно получить за один раз. Это требуется для отрисовки доски в приложении.
POST /board
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
}
В случае успеха метод возвращает код 200 и передаёт в теле ответа JSON:
{
"id": 1234567890,
"author": 1234567890,
"shared_with": [1, 2, 3,],
"title": "<Заголовок доски>",
"cards": [{}, {}, {},],
"background_color": "#<Цвет RRGGBB>"
}
Помимо этого, метод может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
У каждой доски можно менять её заголовок и цвет фона.
PATCH /board
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"title": "<Заголовок доски>",
"background_color": "#<Цвет RRGGBB>",
"header_background_color": "#<Цвет RRGGBB>",
"header_text_color": "#<Цвет RRGGBB>"
}
В JSON также можно передавать только title или только background_color вместо отправки всех сразу.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
Удаление доски происходит в два этапа: сначала её идентификатор удаляется из shared_boards всех ассоциированных пользователей, а затем - уже из таблицы boards.
DELETE /board
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
Карточки отделяют типы задач внутри одной доски.
PUT /card
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card": {
"id": 1234567890,
"author": 1234567890,
"title": "<Заголовок карточки>",
"tasks": [{},{},{},],
"header_background_color": "#xxxxxx",
"header_text_color": "#xxxxxx",
"background_color": "#xxxxxx"
}
}
В поле card->tasks
можно передавать валидные вложенные структуры задач.
Чтобы избежать коллизии нескольких id, все идентификаторы - карточки, вложенных задач и подзадач - будут переназначены. При этом метод возвращает только идентификатор карточки. Авторство всех вложенных сущностей также будет за пользователем, вызвавшим метод.
Метод возвращает код 200 в случае успеха и передаёт в теле ответа идентификатор карточки. Помимо этого, метод может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
В карточках можно менять заголовок, цвет текста и цвет фона.
PATCH /card
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"title": "<Заголовок карточки>",
"header_background_color": "#xxxxxx",
"header_text_color": "#xxxxxx",
"background_color": "#xxxxxx"
}
Поля title
, header_background_color
, header_text_color
и background_color
опциональные.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
Вместе с карточкой удаляются её задачи и подзадачи.
DELETE /card
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PUT /task
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task": {
"id": 1234567890,
"author": 1234567890,
"title": "<Задача>",
"executors": [],
"exec": false,
"subtasks": [{},{},{},],
"notes": "<Заметки>",
"tags": [{...},{...},{...},],
"timelines": {...}
}
}
В поле task->subtasks
можно передавать валидные вложенные структуры подзадач.
Чтобы избежать коллизии нескольких id, все идентификаторы - задачи и вложенных подзадач - будут переназначены. При этом метод возвращает только идентификатор задачи. Авторство всех вложенных сущностей также будет за пользователем, вызвавшим метод. Исполнители задачи и подзадач будут назначены только при условии, что исполнителю доступна доска.
Метод возвращает код 200 в случае успеха и передаёт в теле ответа идентификатор задачи. Помимо этого, метод может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
В задачах впервые появляются метки-теги:
[
{
"id": 1234567890,
"title": "<Метка>",
"text_color": "#xxxxxx",
"background_color": "#xxxxxx"
},
]
Набор таких меток есть и у подзадач. Такие методы изложены ниже (см. Получение тегов).
В задачах впервые появляются ещё и временные рамки:
{
"preferred_time": 1234567890,
"max_time": 1234567890,
"expected_time": 1234567890
}
Первые два параметра представляют из себя количество секунд с эпохи Unix (00:00 1 января 1970 года). Параметр expected_time
хранит количество минут, примерно требующихся для выполнения задачи.
Важно, что временные рамки передавать обязательно всегда. Если временные рамки не установлены пользователем, установите их в значение 0.
Свои временные рамки есть у задач и подзадач. Редактировать временные рамки можно при помощи методов /task/time
и /subtask/time
(см. пункты 19 и 24).
PATCH /task
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"title": "<Задача>",
"executors": [],
"exec": false,
"notes": "<Заметки>"
}
Ключи "title", "executors", "exec" и "notes" опциональны и могут отправляться только в случае наличия изменений.
Исполнители задачи будут назначены только при условии, что исполнителю доступна данная доска.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
DELETE /task
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PATCH /task/time
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"timelines": {
"preferred_time": 1234567890,
"max_time": 1234567890,
"expected_time": 1234567890
}
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PUT /subtask
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask": {
"id": 1234567890,
"author": 1234567890,
"title": "<Подзадача>",
"executors": [],
"exec": false,
"tags": [{...},{...},{...},],
"timelines": {...}
}
}
Обратите внимание на содержимое значений "tags" и "timelines" (см. пункт 12.1 и 12.2).
Исполнители подзадачи будут назначены только при условии, что исполнителю доступна доска.
Метод возвращает код 200 в случае успеха и передаёт в теле ответа идентификатор подзадачи. Помимо этого, метод может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PATCH /subtask
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
"title": "<Заголовок карточки>",
"executors": [],
"exec": false
}
Ключи "title", "executors" и "exec" опциональны и могут отправляться только в случае наличия изменений.
Исполнители подзадачи будут назначены только при условии, что исполнителю доступна данная доска.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
DELETE /subtask
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PATCH /subtask/time
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
"timelines": {
"preferred_time": 1234567890,
"max_time": 1234567890,
"expected_time": 1234567890
}
}
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
GET /tags
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
}
Параметр subtask_id
не передаётся, если нужно получить теги задачи task_id
.
Метод возвращает код 200 в случае успеха и список тегов задачи/подзадачи и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PUT /tag
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
"tag": {
"id": 1234567890,
"title": "<Текст метки>",
"text_color": "#xxxxxx",
"background_color": "#xxxxxx"
}
}
Параметр subtask_id
не передаётся, если нужно создать тег в задаче task_id
.
Метод возвращает код 200 в случае успеха и идентификатор тега и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
PATCH /tag
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
"tag_id": 1234567890,
"title": "<Текст метки>",
"text_color": "#xxxxxx",
"background_color": "#xxxxxx"
}
Параметр subtask_id
не передаётся, если нужно изменить тег задачи task_id
. Параметры title
, text_color
и background_color
опциональны.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.
DELETE /tag
Для работы метода необходимо передать токен в заголовке App-Token
, а в теле запроса - закодированный в base64 JSON вида:
{
"board_id": 1234567890,
"card_id": 1234567890,
"task_id": 1234567890,
"subtask_id": 1234567890,
"tag_id": 1234567890
}
Параметр subtask_id
не передаётся, если нужно удалить тег в задаче task_id
.
Метод возвращает код 200 в случае успеха и может возвращать коды 400, 401, 500 в случае ошибки. Текст ошибки передаётся в теле.