Описание API Foodgram

Этот файл содержит описание API Foodgram. API предоставляет доступ к функциональности приложения Foodgram, которое позволяет пользователям создавать, просматривать и управлять рецептами, подписываться на других пользователей и многое другое.

Доступные методы

Получение списка пользователей

• Метод: GET
• Путь: /api/users/
• Описание: Возвращает список всех пользователей.
• Параметры:
  • page (необязательный): Номер страницы.
  • limit (необязательный): Количество объектов на странице.
• Ответ:
  • 200 OK: Список пользователей.
  • 401 Unauthorized: Неавторизованный доступ.

Получение пользователя по ID

• Метод: GET
• Путь: /api/users/{id}/
• Описание: Возвращает пользователя по уникальному идентификатору.
• Параметры:
  • id (обязательный): Уникальный идентификатор пользователя.
• Ответ:
  • 200 OK: Информация о пользователе.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Пользователь не найден.

Создание пользователя

• Метод: POST
• Путь: /api/users/
• Описание: Создает нового пользователя.
• Параметры: Тело запроса с данными пользователя.
• Ответ:
  • 201 Created: Пользователь успешно создан.
  • 400 Bad Request: Ошибка валидации данных.
  • 401 Unauthorized: Неавторизованный доступ.

Редактирование пользователя

• Метод: PUT
• Путь: /api/users/{id}/
• Описание: Редактирует данные пользователя.
• Параметры:
  • id (обязательный): Уникальный идентификатор пользователя.
• Ответ:
  • 200 OK: Данные пользователя успешно изменены.
  • 400 Bad Request: Ошибка валидации данных.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Пользователь не найден.

Удаление пользователя

• Метод: DELETE
• Путь: /api/users/{id}/
• Описание: Удаляет пользователя по уникальному идентификатору.
• Параметры:
  • id (обязательный): Уникальный идентификатор пользователя.
• Ответ:
  • 204 No Content: Пользователь успешно удален.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Пользователь не найден.

Получение списка рецептов

• Метод: GET
• Путь: /api/recipes/
• Описание: Возвращает список всех рецептов.
• Параметры:
  • page (необязательный): Номер страницы.
  • limit (необязательный): Количество объектов на странице.
• Ответ:
  • 200 OK: Список рецептов.
  • 401 Unauthorized: Неавторизованный доступ.

Создание рецепта

• Метод: POST
• Путь: /api/recipes/
• Описание: Создает новый рецепт.
• Параметры: Тело запроса с данными рецепта.
• Ответ:
  • 201 Created: Рецепт успешно создан.
  • 400 Bad Request: Ошибка валидации данных.
  • 401 Unauthorized: Неавторизованный доступ.

Редактирование рецепта

• Метод: PUT
• Путь: /api/recipes/{id}/
• Описание: Редактирует данные рецепта.
• Параметры:
  • id (обязательный): Уникальный идентификатор рецепта.
• Ответ:
  • 200 OK: Данные рецепта успешно изменены.
  • 400 Bad Request: Ошибка валидации данных.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Рецепт не найден.

Удаление рецепта

• Метод: DELETE
• Путь: /api/recipes/{id}/
• Описание: Удаляет рецепт по уникальному идентификатору.
• Параметры:
  • id (обязательный): Уникальный идентификатор рецепта.
• Ответ:
  • 204 No Content: Рецепт успешно удален.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Рецепт не найден.

Получение списка ингредиентов

• Метод: GET
• Путь: /api/ingredients/
• Описание: Возвращает список всех ингредиентов с возможностью поиска по имени.
• Параметры:
  • name (необязательный): Поиск по частичному вхождению в начало названия ингредиента.
• Ответ:
  • 200 OK: Список ингредиентов.
  • 401 Unauthorized: Неавторизованный доступ.

Получение ингредиента по ID

• Метод: GET
• Путь: /api/ingredients/{id}/
• Описание: Возвращает ингредиент по уникальному идентификатору.
• Параметры:
  • id (обязательный): Уникальный идентификатор ингредиента.
• Ответ:
  • 200 OK: Информация об ингредиенте.
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Ингредиент не найден.

Получение списка подписок

• Метод: GET
• Путь: /api/users/subscriptions/
• Описание: Возвращает список пользователей, на которых подписан текущий пользователь. Включает в себя также рецепты.
• Параметры:
  • page (необязательный): Номер страницы.
  • limit (необязательный): Количество объектов на странице.
  • recipes_limit (необязательный): Количество рецептов для каждого пользователя.
• Ответ:
  • 200 OK: Список объектов текущей страницы.
  • 401 Unauthorized: Неавторизованный доступ.

Подписка на пользователя

• Метод: POST
• Путь: /api/users/{id}/subscribe/
• Описание: Подписывает текущего пользователя на другого пользователя.
• Параметры:
  • id (обязательный): Уникальный идентификатор пользователя, на которого подписываемся.
  • recipes_limit (необязательный): Количество рецептов для каждого пользователя.
• Ответ:
  • 201 Created: Подписка успешно создана.
  • 400 Bad Request: Ошибка подписки (например, если уже подписан или при подписке на себя самого).
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Пользователь, на которого подписываемся, не найден.

Отписка от пользователя

• Метод: DELETE
• Путь: /api/users/{id}/subscribe/
• Описание: Отменяет подписку текущего пользователя на другого пользователя.
• Параметры:
  • id (обязательный): Уникальный идентификатор пользователя, от которого отписываемся.
• Ответ:
  • 204 No Content: Успешная отписка.
  • 400 Bad Request: Ошибка отписки (например, если не был подписан).
  • 401 Unauthorized: Неавторизованный доступ.
  • 404 Not Found: Пользователь, от которого отписываемся, не найден.

Получение токена авторизации

• Метод: POST
• Путь: /api/auth/token/login/
• Описание: Используется для авторизации по электронной почте и паролю, чтобы далее использовать токен при запросах.
• Параметры: Тело запроса с данными авторизации.
• Ответ:
  • 201 Created: Токен успешно создан и возвращен.
  • 401 Unauthorized: Ошибка авторизации.

Удаление токена

• Метод: POST
• Путь: /api/auth/token/logout/
• Описание: Удаляет токен текущего пользователя, разлогинив его.
• Параметры: Отсутствуют.
• Ответ:
  • 204 No Content: Токен успешно удален.
  • 401 Unauthorized: Неавторизованный доступ.

Схемы данных

В API используются следующие схемы данных:

• User: Схема пользователя.
• Recipe: Схема рецепта.
• Ingredient: Схема ингредиента.
• Tag: Схема тега.
• Subscription: Схема подписки.

Каждая из этих схем имеет определенные поля и структуру данных. Подробное описание схем данных можно найти в разделе "components/schemas" в файле API спецификации.

Схемы данных

CustomUserCreate

Схема для создания пользовательской записи.

• email (string, format: email, maxLength: 254): Адрес электронной почты.
• id (integer, readOnly: true): Уникальный идентификатор пользователя.
• username (string, maxLength: 150, pattern: ^[\w.@+-]+\z): Уникальный юзернейм.
• first_name (string, maxLength: 150): Имя пользователя.
• last_name (string, maxLength: 150): Фамилия пользователя.
• password (string, maxLength: 150): Пароль пользователя.

CustomUserResponseOnCreate

Схема для ответа после успешного создания пользователя.

• email (string, format: email, maxLength: 254): Адрес электронной почты.
• id (integer, readOnly: true): Уникальный идентификатор пользователя.
• username (string, maxLength: 150): Уникальный юзернейм.
• first_name (string, maxLength: 150): Имя пользователя.
• last_name (string, maxLength: 150): Фамилия пользователя.

Activation

Схема данных для активации пользователя.

• uid (string): Уникальный идентификатор пользователя.
• token (string): Токен активации.

SendEmailReset

Схема данных для отправки запроса на сброс пароля по электронной почте.

• email (string, format: email): Адрес электронной почты.

PasswordResetConfirm

Схема данных для подтверждения сброса пароля.

• uid (string): Уникальный идентификатор пользователя.
• token (string): Токен сброса пароля.
• new_password (string): Новый пароль пользователя.

UsernameResetConfirm

Схема данных для подтверждения смены юзернейма.

• new_email (string, format: email, maxLength: 254): Новый адрес электронной почты.

SetPassword

Схема данных для установки нового пароля.

• new_password (string): Новый пароль пользователя.
• current_password (string): Текущий пароль пользователя.

SetUsername

Схема данных для смены юзернейма.

• current_password (string): Текущий пароль пользователя.
• new_email (string, format: email, maxLength: 254): Новый адрес электронной почты.

TokenCreate

Схема данных для создания токена авторизации.

• password (string): Пароль пользователя.
• email (string): Адрес электронной почты пользователя.

TokenGetResponse

Схема данных для ответа с токеном авторизации.

• auth_token (string): Токен авторизации пользователя.

RecipeCreateUpdate

Схема данных для создания или обновления рецепта.

• id (integer, readOnly: true): Уникальный идентификатор рецепта.
• ingredients (array): Список ингредиентов в рецепте.
  • id (integer): Уникальный идентификатор ингредиента.
  • amount (integer): Количество ингредиента в рецепте.
• tags (array): Список идентификаторов тегов.
• image (string, format: binary): Картинка, закодированная в Base64.
• name (string, maxLength: 200): Название рецепта.
• text (string): Описание рецепта.
• cooking_time (integer, minimum: 1): Время приготовления рецепта.

Лицензия

Этот проект распространяется под лицензией MIT.