В этом проекте вы напишете полноценное API для проекта Yatube и оформите документацию к нему. Вас ждут такие задачи:
  1. Развернуть проект (клонировать репозиторий, установить зависимости из requirements.txt).
  2. Подключить аутентификацию по JWT-токену.
  3. Изучить документацию и доделать проект на её основе.
Традиционно, перед выполнением финального задания спринта мы дадим дополнительную информацию.
У вас в репозитории появился проект api_final_yatube, клонируйте его в свою рабочую директорию Dev.
Активируйте виртуальное окружение и установите все необходимые пакеты:
Скопировать кодBASH
pip install -r requirements.txt

Аутентификация по JWT-токену

Токен, созданный по стандарту JWT (JSON Web Token), состоит из трёх частей. Каждая из них записывается в формате JSON:
  • header (англ. «заголовок») содержит служебную информацию;
  • payload (англ. «полезная нагрузка») хранит основные данные токена;
  • signature (англ. «подпись») — подпись, ключ безопасности для защиты информации.
После подготовки каждая из частей кодируется алгоритмом Base64Url. Получившиеся строки разделяются между собой точками:
image

Header JWT

Хедер, как правило, содержит два поля:
  • тип токена — это строка "JWT";
  • алгоритм создания подписи — обычно применяется алгоритм HMAC SHA256 или RSA:
Скопировать кодJAVASCRIPT
{
    "alg": "HS256",
    "typ": "JWT"
}

Payload JWT

Пейлоуд хранит закодированную информацию для аутентификации, тип токена и timestamp с временем его действия:
Скопировать кодJAVASCRIPT
{
  "token_type": "access",
  "exp":1578171903, 
  "user_id":5
}

Signature JWT

Подпись гарантирует, что содержимое хедера и пейлоуда не были изменены после создания токена. Специальный алгоритм генерирует подпись, исходя из содержимого хедера и пейлоуда. При кодировании этот алгоритм использует секретный ключ, который известен только серверу.
Для генерации JWT подключите библиотеку Simple JWT:
Скопировать кодBASH
pip install djangorestframework-simplejwt
Обновите файл настроек settings.py:
Скопировать кодPYTHON
    REST_FRAMEWORK = {
        'DEFAULT_AUTHENTICATION_CLASSES': [
            'rest_framework_simplejwt.authentication.JWTAuthentication',
        ],
    }
Обновите файл роутинга urls.py:
Скопировать кодPYTHON
    from rest_framework_simplejwt.views import (
        TokenObtainPairView,
        TokenRefreshView,
    )
    
    urlpatterns = [
        path('api/v1/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
        path('api/v1/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
    ]
Готово.
Теперь можно выполнить POST-запрос localhost:8000/api/v1/token/ передав поля username и password. API вернет JWT-токен:
Скопировать кодJSON
    {
        "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTU4NzEyODUzNSwianRpIjoiNzRmMDhkOGEwODQ4NGEzYjgyZmM4MDRhMTQ3ZTEyZmIiLCJ1c2VyX2lkIjoxfQ.GW7Obcvy2TWgsEI5lqSx9BC1mxk0WnsywBHrXScs7bI",
        "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTg3MDQyNDM1LCJqdGkiOiI5ZmNjMWE5YTM5NDQ0Y2Q4OWJlOGFlOGRlYWQxNDE0ZSIsInVzZXJfaWQiOjF9.ZkEdzDN5pNgYToDRJq1CKHjIglK1ir1fhnfcXkmziuk"
    }
Токен вернётся в поле access, а данные из поля refresh пригодятся для обновления токена. Чтобы обновить токен (например, в случае компрометации), отправьте POST-запрос на тот же адрес, а в поле refresh передайте refresh-токен (если повторно передать логин и пароль — токен не будет обновлён: вам просто вернётся прежний токен).
При отправке запроса передавайте токен в заголовке Authorization: Bearer <токен>
Слово Bearer здесь заменяет слово Token и означает, что за ним следует сам токен.
Дополнительные настройки можно найти в документации: например, параметр ACCESS_TOKEN_LIFETIME позволит настроить время жизни токена.

Документирование API

API обязательно должен быть документирован: структура запросов и ответов неизвестна никому, кроме разработчиков API, и без документации никто не сможет понять, как работать с системой.
Основа документирования — файл README.md, его сохраняют в корневой директории репозитория. Обычно он содержит несколько разделов:
  • Описание. Что это за проект, какую задачу он решает, в чём его польза.
  • Установка. Как развернуть проект на локальной машине.
  • Примеры. Примеры запросов к API.
Заполнять README.md удобно прямо на Гитхабе. В файлах .md для форматирования текста (для добавления заголовков, оформления ссылок, выделения текста жирным или курсивом) разрешена разметка Markdown. Не пренебрегайте ей, это улучшит читабельность вашего текста.
Объёмную документацию больших проектов выносят в отдельный сайт с навигацией и поиском. Для создания таких сайтов-справочников есть множество удобных инструментов: например, генератор MkDocs поможет создать многостраничный сайт с документацией и захостить его на Гитхабе.
Стандарт документирования OpenAPI описывает, как должен выглядеть файл с документацией. Есть два популярных решения для создания документации в формате HTML: — Redoc и Swagger.

Задание

Есть распространённый способ проектирования, согласно которому сначала составляют документацию, а потом, основываясь на ней как на техническом задании, пишут программную часть API.
Именно так мы предлагаем поступить в этом задании.
Когда вы запустите проект с заданием на своём компьютере, по адресу http://localhost:8000/redoc/ будет доступна документация по API Yatube. В документации описано, как должен работать ваш API. Документация создана на Redoc.
Сейчас проект не соответствует документации: часть кода не написана.
Ваша задача — дописать код и привести его в соответствие с документацией: добавить недостающие модели, шаблоны адресов и View для обработки запросов, описанных в доках. Документация — это ваше техническое задание.
Например, в документации описана модель Follow, в ней есть два поля — user (кто подписан) и following (на кого подписан). Для этой модели в документации описан эндпоинт /follow и два метода:
  • GET (возвращает всех подписчиков пользователя, сделавшего запрос и может фильтровать по параметру search)
  • POST — чтобы подписаться на кого-то
Но ни самой модели Follow, ни обработчиков запросов в коде нет. Надо их написать.
Убедитесь, что все остальные модели и запросы, описанные в документации, существуют и работают корректно. Допишите недостающее.
image