What to watch

Описание API-методов

Регистрация пользователя POST /api/register

Пользователь заполняет форму регистрации указав Имя, email, пароль и подтверждение пароля.

Дополнительно может быть загружен аватар.

Последовательность действий:

• Отправка post запроса с данными пользователя на endpoint регистрации.

• Валидация полученных полей. Проверка наличия обязательных полей и соответствия заданным правилам.

• Проверка, что указанный email не занят.

• Сохранение данных в БД, или возвращение списка ошибок при их наличии.

• Сохранение аватара в публичное хранилище и указание ссылки на файл в таблице пользователей.

• Возвращение токена для аутентификации пользователя под зарегистрированной учетной записью.

Правила валидации:

Аутентификация POST /api/login

Правила валидации:

Пользователь заполняет форму авторизации, указав email и пароль.

• Отправка post запроса с данными пользователя на endpoint авторизации.

• Валидация полученных полей. Проверка наличия обязательных полей и соответствия заданным правилам.

• Возвращение токена для аутентификации пользователя.

Правила валидации:

Метод возвращает токен аутентификации.

Получение профиля пользователя GET /api/user

Метод возвращает информацию о пользователе: имя, email, аватар и роль пользователя.

Метод доступен только аутентифицированному пользователю.

Обновление профиля пользователя PATCH /api/user

С помощью данного метод пользователь может изменить свое имя, email, пароль или загрузить аватар.

Правила валидации:

Метод доступен только аутентифицированному пользователю.

Выход (logout) POST /api/logout

Отправка post запроса на endpoint выхода пользователя.

Уничтожение токена пользовательской аутентификации.

Получение списка фильмов GET /api/films

Страница представляет собой список по 8 фильмов с пагинацией.

Информация о фильме содержит название, превью обложки (изображение для отображения в списке), превью видео (ссылка на превью) и другую дополнительную информацию для построения пагинации.

Есть возможность отсортировать список по дате выхода и рейтингу фильма.

По умолчанию фильмы сортируются по дате выхода, от новых к старым (desc).

Этот же endpoint может использоваться для получения списка фильмов по жанру.

• Отправка get запроса на endpoint получения списка фильмов

• Возвращение первых 8 фильмов, если не передано другое условие (параметр page)
  • Вместе со списком сериалов возвращаются параметры пагинации: количество элементов всего ссылка на первую страницу, на последнюю, на предыдущую и следующую

Дополнительно вместе с запросом могут быть переданы следующие параметры:

• page — номер страницы, для пагинации

• genre — фильтрация по жанру

• status — фильтрация по статусу, по умолчанию значение ready, пользователь с ролью модератор может изменить значение на (pending, moderate)

• order_by — правило сортировки. Возможные значения: released, rating

• order_to — направление сортировки. Возможные значения: asc, desc

Получение информации о фильме GET /api/films/{id}

При получении информации о фильме с идентификатором id пользователь видит следующую информацию:

• Большой постер

• Превью (маленькое изображение)

• Обложка фильма

• Цвет фона для карточки фильма

• Название фильма

• Жанры

• Год выхода на экраны

• Описание

• Режиссёр

• Список актёров

• Продолжительность фильма

• Ссылка на видео

• Ссылка на превью видео

• Рейтинг фильма, в виде числа, к-во голосов

Если запрос выполняет авторизованный пользователь — в дополнение к другим данным, возвращается статус наличия фильма в избранном.

В случае попытки обращения к несуществующему фильму, ожидается возврат 404 ошибки.

Получение списка жанров GET /api/genres

Технический endpoint. Для формирования списка жанров в форме поиска или каталоге.

Редактирование жанра PATCH /api/genres/{genre}

Метод доступен только аутентифицированному пользователю с ролью модератор.

Получение списка фильмов добавленных пользователем в избранное GET /api/favorite

Метод возвращает список фильмов, добавленных пользователем в избранное (список «К просмотру»).

Формат и информация возвращаемая в этом списке аналогична методу для получения списка фильмов.

Фильмы возвращаются в порядке добавления пользователем в список, от новых к старым.

Метод доступен только аутентифицированному пользователю.

Добавление фильма в избранное POST /api/films/{id}/favorite/

Метод принимает на вход id добавляемого фильма.

В случае попытки добавления несуществующего фильма, ожидается возврат 404 ошибки.

В случае попытки добавления в избранное фильма который уже присутствует в списке пользователя — ошибка 422, с соответствующим сообщением (message).

Метод доступен только аутентифицированному пользователю.

Удаление фильма из избранного DELETE /api/films/{id}/favorite/

Метод принимает на вход id удаляемого фильма.

В случае попытки удаления несуществующего фильма, ожидается возврат 404 ошибки.

В случае попытки удаления фильма, который отсутствует в списке пользователя, — ошибка 422, с соответствующим сообщением (message).

Метод доступен только аутентифицированному пользователю.

Получение списка похожих фильмов GET /api/films/{id}/similar

Отправляя на роут получения похожих фильмов с указанием id фильма для которого запрашиваются похожие, метод возвращает список из 4 подходящих фильмов.

Похожесть определяется принадлежностью к тем же жанрам, что и исходный фильм (любым из имеющихся).

Формат и информация возвращаемая в этом списке аналогична методу для получения списка фильмов.

Получение списка отзывов к фильму GET /api/comments/{id}

Метод принимает на вход id фильма, в случае отсутствия такового — возвращается 404 ошибка.

Возвращает список отзывов. Каждый отзыв содержит: текст отзыва, имя автора, дату написания отзыва. Также может содержать оценку.

Отзывы, загруженные из внешнего источника, возвращаются в общем списке с именем автора «Гость» Отзывы отсортированы от наиболее новых к старым (desc).

Добавление отзыва к фильму POST /api/comments/{id}

В качестве параметра в адресе указывается id фильма к которому добавляется комментарий.

Комментарий может быть добавлен отдельно, так и в ответ на другой, в этом случае в теле запроса указывается и comment_id.

Добавление отзыва сопровождается выставлением оценки.

Метод доступен только аутентифицированному пользователю.

Правила валидации:

Редактирование комментария PATCH /api/comments/{comment}

Метод доступен только аутентифицированному пользователю.

Пользователь может отредактировать свой комментарий.

Модератор может отредактировать любой комментарий.

Правила валидации:

Удаление комментария DELETE /api/comments/{comment}

Метод доступен только аутентифицированному пользователю.

Пользователь может удалить свой комментарий, при условии, что комментарий не содержит ответов.

Модератор может удалить любой комментарий.

При удалении комментария, имеющего ответы, удаляются все его потомки.

Получение промо-фильма GET /api/promo

Метод, возвращающий фильм, являющийся продвигаемым на данный момент (promo).

Формат и информация возвращаемая в этом списке аналогична методу для получения информации о фильме.

Установка промо-фильма POST /api/promo/{id}

Метод доступен только аутентифицированному пользователю с ролью модератор.

При отсутствии запрошенного в роуте фильма в базе, на запрос возвращается 404 ошибка.

Добавление фильма в базу POST /api/films

Модератор указывает в форме идентификатор фильма с сайта imdb вида tt0111161.

Создается фоновая задача, которая запрашивает данные о фильме из внешнего источника, и обновляет информацию о фильме в базе.

В момент создания заявки, фильм сохраняется только с imdb_id и статусом «в ожидании» (pending).

После загрузки данных, статус меняется на «на модерации» (moderate). Модератор может получить список фильмов с этим статусом, отредактировать его, заполнить недостающие поля, указать ссылки на видео и прочее, после чего поставить статус «готов» (ready) — после чего фильм будет доступен пользователям.

Для получения информации о фильме можно использовать сервис http://www.omdbapi.com (или api htmlacademy)

Метод доступен только аутентифицированному пользователю с ролью модератор.

Правила валидации:

При заполнении поля imdb_id и наличии фильма с таким id в базе — возвращается ошибка валидации 422.

При сохранении проверяем наличие связанных жанров и создаем при отсутствии.

Редактирование фильма PATCH /api/films/{id}

Модератор может изменить информацию о фильме или заполнить недостающие данные после добавления фильма.

Метод доступен только аутентифицированному пользователю с ролью модератор.

Правила валидации:

При отсутствии запрошенного в роуте фильма в базе, возвращается 404 ошибка.