API YaMDb

API YaMDb - групповой учебный проект на Django REST Framework для сервиса, который собирает отзывы пользователей на произведения: книги, фильмы, музыку и другие категории.

В YaMDb не хранятся сами произведения: через API нельзя посмотреть фильм, прочитать книгу или послушать музыку. Проект хранит информацию о произведениях, категориях, жанрах, пользовательских отзывах, оценках и комментариях.

Описание проекта

YaMDb решает задачу централизованного сбора пользовательских мнений о произведениях.

Пользователи могут:

• просматривать произведения, категории и жанры;
• читать отзывы и комментарии;
• регистрироваться и получать JWT-токен;
• оставлять один отзыв на одно произведение;
• ставить оценку произведению от 1 до 10;
• комментировать отзывы других пользователей;
• редактировать и удалять собственные отзывы и комментарии.

Модераторы могут редактировать и удалять любые отзывы и комментарии.

Администраторы могут управлять пользователями, категориями, жанрами и произведениями.

Рейтинг произведения формируется на основе пользовательских оценок.

Основные возможности

• регистрация пользователей по username и email;
• отправка кода подтверждения confirmation_code на email;
• получение JWT-токена по username и confirmation_code;
• ролевая модель доступа: user, moderator, admin;
• управление пользователями через API;
• CRUD для произведений;
• создание и удаление категорий и жанров;
• создание, просмотр, редактирование и удаление отзывов;
• создание, просмотр, редактирование и удаление комментариев;
• ограничение: один пользователь может оставить только один отзыв на одно произведение;
• оценка произведения целым числом от 1 до 10;
• фильтрация произведений по категории, жанру, названию и году;
• поиск по категориям, жанрам и пользователям;
• пагинация ответов;
• импорт начальных данных из CSV-файлов;
• документация API через ReDoc.

Технологии

• Python
• Django
• Django REST Framework
• Simple JWT
• django-filter
• SQLite
• pytest
• Postman

Роли пользователей и права доступа

Роль	Права
Аноним	Может читать произведения, категории, жанры, отзывы и комментарии.
user	Может читать всё, создавать отзывы и комментарии, редактировать и удалять свои отзывы и комментарии.
moderator	Имеет права пользователя, а также может редактировать и удалять любые отзывы и комментарии.
admin	Имеет полные права на управление пользователями, категориями, жанрами и произведениями.
Суперпользователь Django	Всегда обладает правами администратора.

Установка и запуск проекта

1. Клонировать репозиторий

git clone https://github.com/psa88/api-yamdb.git
cd api-yamdb

2. Создать и активировать виртуальное окружение

Для Windows PowerShell:

python -m venv venv
.\venv\Scripts\Activate.ps1

Для macOS/Linux:

python3 -m venv venv
source venv/bin/activate

3. Установить зависимости

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Перейти в директорию с manage.py

cd api_yamdb

5. Выполнить миграции

python manage.py migrate

6. Загрузить данные из CSV-файлов

В проекте подготовлены CSV-файлы с начальными данными. Они находятся в директории:

api_yamdb/static/data/

Для загрузки данных выполните команду:

python manage.py load_csv

Команда загружает данные из файлов:

• users.csv;
• category.csv;
• genre.csv;
• titles.csv;
• genre_title.csv;
• review.csv;
• comments.csv.

7. Создать суперпользователя

python manage.py createsuperuser

8. Запустить сервер разработки

python manage.py runserver

После запуска проект будет доступен по адресу:

http://127.0.0.1:8000/

Документация API доступна по адресу:

http://127.0.0.1:8000/redoc/

Переменные окружения

Проект может работать без отдельного .env, так как в настройках предусмотрены значения по умолчанию. При необходимости можно создать файл .env в директории api_yamdb/:

SECRET_KEY=your-secret-key
DEBUG=True

В проекте используется консольный backend для email:

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

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

Основные эндпоинты API

Все запросы к API начинаются с префикса:

/api/v1/

Ресурс	Эндпоинт	Описание
Auth	/api/v1/auth/signup/	Регистрация пользователя и получение кода подтверждения.
Auth	/api/v1/auth/token/	Получение JWT-токена.
Users	/api/v1/users/	Управление пользователями. Доступно администратору.
Users	/api/v1/users/me/	Просмотр и редактирование собственного профиля.
Categories	/api/v1/categories/	Получение списка и создание категорий.
Genres	/api/v1/genres/	Получение списка и создание жанров.
Titles	/api/v1/titles/	Получение списка и создание произведений.
Reviews	/api/v1/titles/{title_id}/reviews/	Отзывы к произведению.
Comments	/api/v1/titles/{title_id}/reviews/{review_id}/comments/	Комментарии к отзыву.

Примеры запросов к API

Ниже приведены примеры запросов через curl.

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

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/auth/signup/ \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "username": "new_user"}'

Пример ответа:

{
  "email": "user@example.com",
  "username": "new_user"
}

После запроса код подтверждения будет выведен в консоль сервера.

Получение JWT-токена

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "new_user", "confirmation_code": "your_confirmation_code"}'

Пример ответа:

{
  "token": "jwt_token"
}

Далее токен нужно передавать в заголовке Authorization:

Authorization: Bearer <jwt_token>

Получение списка произведений

Запрос:

curl http://127.0.0.1:8000/api/v1/titles/

Пример ответа:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Побег из Шоушенка",
      "year": 1994,
      "rating": 9,
      "description": "Описание произведения",
      "genre": [
        {
          "name": "Драма",
          "slug": "drama"
        }
      ],
      "category": {
        "name": "Фильм",
        "slug": "movie"
      }
    }
  ]
}

Создание категории администратором

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/categories/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -d '{"name": "Книги", "slug": "books"}'

Пример ответа:

{
  "name": "Книги",
  "slug": "books"
}

Создание произведения администратором

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/titles/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -d '{
    "name": "Марсианские хроники",
    "year": 1950,
    "description": "Сборник рассказов Рэя Брэдбери.",
    "genre": ["sci-fi"],
    "category": "books"
  }'

Пример ответа:

{
  "id": 1,
  "name": "Марсианские хроники",
  "year": 1950,
  "rating": null,
  "description": "Сборник рассказов Рэя Брэдбери.",
  "genre": [
    {
      "name": "Фантастика",
      "slug": "sci-fi"
    }
  ],
  "category": {
    "name": "Книги",
    "slug": "books"
  }
}

Создание отзыва авторизованным пользователем

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/titles/1/reviews/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user_token>" \
  -d '{"text": "Отличное произведение.", "score": 10}'

Пример ответа:

{
  "id": 1,
  "text": "Отличное произведение.",
  "author": "new_user",
  "score": 10,
  "pub_date": "2026-04-28T12:00:00Z"
}

Создание комментария к отзыву

Запрос:

curl -X POST http://127.0.0.1:8000/api/v1/titles/1/reviews/1/comments/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user_token>" \
  -d '{"text": "Полностью согласен с отзывом."}'

Пример ответа:

{
  "id": 1,
  "text": "Полностью согласен с отзывом.",
  "author": "new_user",
  "pub_date": "2026-04-28T12:05:00Z"
}

Фильтрация и поиск

Фильтрация произведений

Произведения можно фильтровать по категории, жанру, названию и году:

GET /api/v1/titles/?category=movie
GET /api/v1/titles/?genre=drama
GET /api/v1/titles/?name=марсианские
GET /api/v1/titles/?year=1950

Поиск

Для категорий, жанров и пользователей доступен поиск:

GET /api/v1/categories/?search=книги
GET /api/v1/genres/?search=драма
GET /api/v1/users/?search=admin

Проверка проекта

Запуск pytest

Из корня проекта выполните:

pytest

Проверка flake8

flake8

Проверка через Postman

В директории postman_collection/ находится коллекция запросов:

postman_collection/Ymdb-collection.postman_collection.json

Для подготовки базы данных к запуску коллекции можно использовать скрипт:

cd postman_collection
bash set_up_data.sh

Cкрипт очищает текущую базу данных и создаёт пользователей, необходимые для проверки API через Postman.

Подробная инструкция находится в файле:

postman_collection/README.md

Работа с данными и удалением связанных объектов

В проекте реализованы связи между объектами:

• при удалении пользователя удаляются его отзывы и комментарии;
• при удалении произведения удаляются отзывы к нему и комментарии к этим отзывам;
• при удалении отзыва удаляются комментарии к нему;
• при удалении категории связанные произведения не удаляются;
• при удалении жанра связанные произведения не удаляются.

Авторы

• Сергей Прядко
• Николь Журбенко
• Андрей Львов