API.md

API

Оглавление

• Настройка базы данных
• Регистрация пользователя
• Вход пользователя в аккаунт и получение токена
• Получение списка досок пользователя
• Создание доски
• Получение доски
• Изменение доски
• Удаление доски
• Создание карточки
• Изменение карточки
• Удаление карточки
• Создание задачи
• Теги
• Временные рамки
• Изменение задачи
• Удаление задачи
• Редактирование временных рамок задачи
• Создание подзадачи
• Изменение подзадачи
• Удаление подзадачи
• Редактирование временных рамок подзадачи
• Получение тегов
• Создание тегов
• Изменение тегов
• Удаление тегов

Примечания

В целом, работа с API выглядит следующим образом:

1. Пользователь регистрируется и/или получает новый токен.
2. Пользователь отправляет запросы с этим токеном.

Сервер умеет манипулировать такими сущностями, как 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 в случае ошибки. Текст ошибки передаётся в теле.

Теги tags

В задачах впервые появляются метки-теги:

[
  {
    "id": 1234567890,
    "title": "<Метка>",
    "text_color": "#xxxxxx",
    "background_color": "#xxxxxx"
  },
]

Набор таких меток есть и у подзадач. Такие методы изложены ниже (см. Получение тегов).

Временные рамки timelines

В задачах впервые появляются ещё и временные рамки:

{
  "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 в случае ошибки. Текст ошибки передаётся в теле.