Web API с помощью Django REST framework
Веб-cервис (англ. web service) — идентифицируемая веб-адресом программная система со стандартизированными интерфейсами. Веб-службы могут взаимодействовать друг с другом и со сторонними приложениями посредством сообщений, основанных на определённых протоколах (XML, JSON и т. д.). Веб-служба является единицей модульности при использовании сервис-ориентированной архитектуры приложения.
Одним из подходов создания веб сервиса является rest.
Rest (сокр. англ. Representational State Transfer, «передача состояния представления») — стиль построения архитектуры распределенного приложения. Данные в REST должны передаваться в виде небольшого количества стандартных форматов (например HTML, XML, JSON). Сетевой протокол (как и HTTP) должен поддерживать кэширование, не должен зависеть от сетевого слоя, не должен сохранять информацию о состоянии между парами «запрос-ответ». Утверждается, что такой подход обеспечивает масштабируемость системы и позволяет ей эволюционировать с новыми требованиями.
Django REST framework — удобный инструмент для работы с rest основанный на идеологии фреймворка Django.
Требования к окружению:
Python (2.6, 2.7)
Django (1.3, 1.4, 1.5)
Установка
Установить можно привычной для нас командой pip:
И можно поставить дополнительные пакеты:
Или же сделать клон проекта с Github:
Не забываем прописать приложение в INSTALLED_APPS:
А также добавить запись в urls.py:
Url можно ставить любой на Ваш вкус, главное подключить файл с урлами rest framework (rest_framework.urls).
Пример использования
Создадим API для работы с пользователями и их группами.
Для начала нам нужно определить некоторые Serializers, которые мы будем использовать
Пропишем views.py
Мы создали функцию api_root, которая будет отправной точкой для нашего API. И четыре класса, для связи с моделями и указали какие serializers нужно при этом использовать.
Добавим ссылки в urls.py
Важный момент использование user-detail и group-detail. Для корректной связи с views.py нужно использовать именование вида
В format_suffix_patterns мы указали суфикс для наших urls.
Settings
Результат
Используя curl в консоли испытаем что же получилось:
В браузере можно увидить что то подобное: 
Кратко о Django Rest Framework
Что такое Django Rest Framework?
Django Rest Framework (DRF) — это библиотека, которая работает со стандартными моделями Django для создания гибкого и мощного API для проекта. Эта статья поможет понять структуру DRF и дать вводные данные для начала его использования
Основная архитектура
API DRF состоит из 3-х слоев: сериализатора, вида и маршрутизатора.
Сериализатор: преобразует информацию, хранящуюся в базе данных и определенную с помощью моделей Django, в формат, который легко и эффективно передается через API.
Вид (ViewSet): определяет функции (чтение, создание, обновление, удаление), которые будут доступны через API.
Маршрутизатор: определяет URL-адреса, которые будут предоставлять доступ к каждому виду.
Сериализаторы
Модели Django интуитивно представляют данные, хранящиеся в базе, но API должен передавать информацию в менее сложной структуре. Хотя данные будут представлены как экземпляры классов Model, их необходимо перевести в формат JSON для передачи через API.
Сериализатор DRF производит это преобразование. Когда пользователь передает информацию (например, создание нового экземпляра) через API, сериализатор берет данные, проверяет их и преобразует в нечто, что Django может сложить в экземпляр модели. Аналогичным образом, когда пользователь обращается к информации через API, соответствующие экземпляры передаются в сериализатор, который преобразовывает их в формат, который может быть легко передан пользователю как JSON.
Наиболее распространенной формой, которую принимает сериализатор DRF, является тот, который привязан непосредственно к модели Django:
Настройки fields позволяют точно указать, какие поля доступны этому сериализатору. В качестве альтернативы, может быть установлен exclude вместо fields, которое будет включать все поля модели, кроме тех, которые указаны в exclude.
Сериализаторы — это невероятно гибкий и мощный компонент DRF. Хотя подключение сериализатора к модели является наиболее распространенным, сериализаторы могут использоваться для создания любой структуры данных Python через API в соответствии с определенными параметрами.
Виды (ViewSets)
Каждая из этих функций может быть переопределена, если требуется другое поведение, но стандартная функциональность работает с минимальным кодом, а именно:
Если необходимы дополнительные настройки, можно использовать общие представления, вместо ModelViewSet или даже отдельные пользовательские представления.
Маршрутизаторы (роутеры)
И наконец, маршрутизаторы: они предоставляют верхний уровень API. Чтобы избежать создания бесконечных URL-адресов вида: «списки», «детали» и «изменить», маршрутизаторы DRF объединяют все URL-адреса, необходимые для данного вида в одну строку для каждого ViewSet, например:
Затем все ViewSet, которые зарегистрированны в маршрутизаторе, можно добавить к обычным url_patterns:
Теперь через API можно получить данные точно так же, как и любые другие обычные страницы Django.
Django REST Framework: REST API на Python с нуля
1. Знакомство с REST
Термин REST API расшифровывается как Representational State Transfer Application Programming Interface. Следовательно, RESTful API — это программный интерфейс приложения, соответствующий ограничениям архитектурного стиля REST.
REST — не протокол и не стандарт. Это, как уже было сказано, архитектурное ограничение. Чтобы API считался RESTful, он должен соответствовать следующим критериям.
Благодаря вышеперечисленным архитектурным правилам REST API масштабируемый, переносимый и гибкий.
2. Что такое Django REST Framework?
Django — масштабируемый полнофункциональный веб-фреймворк, написанный на Python. Django берет на себя все хлопоты, зачастую связанные с веб-разработкой, такие как безопасность и доступ к базам данных.
Существует множество библиотек для Django, расширяющих его функционал. Одна из них, о которой мы поговорим сегодня, — это Django REST Framework или DRF, которая позволяет сериализовать данные из Django ORM через REST API.
Сериализация — это преобразование таблиц из базы данных в формат JSON.
Руководство написано для новичков, прошлый опыт работы с фреймворком Django не предполагается, так как вы многому научитесь прямо сейчас. Кроме того, в статье не будет обширного описания технических нюансов каждой операции. Рассматривайте руководство в качестве упражнения.
Давайте создадим сайт бронирования отелей! Исходный код и справка доступны на GitHub.
3. Установка Django
Прежде чем приступить непосредственно к работе с REST API, сделаем краткий экскурс в Django.
Создаем API блога на Django REST Framefork
API-сервисы позволяют приложениям общаться с другими приложения с помощью данных, передаваемых в формате JSON. Достаточно создать и использовать его данные из любого API-клиента или фронтенд-приложения.
Django REST Framework — это набор инструментов для создания REST API с помощью Django. В этом руководстве рассмотрим, как правильно его использовать. Создадим эндпоинты(точки доступа к ресурсам) для пользователей, постов в блоге, комментариев и категорий.
Также рассмотрим аутентификацию, чтобы только залогиненный пользователь мог изменять данные приложения.
Вот чему вы научитесь:
Требования
У вас в системе должен быть установлен Python 3, желательно 3.8. Также понадобится опыт работы с REST API. Вы должны быть знакомы с реляционными базами данными, включая основные и внешние ключи, модели баз данных, миграции, а также отношения многие-к-одному и многие-ко-многим.
Наконец, потребуется опыт работы с Python и Django.
Настройка проекта
Для создания нового API-проекта для начала создайте виртуальную среду Python в своей рабочей директории. Для этого запустите следующую команду в терминале:
Не забывайте запускать все команды из этого руководства в виртуальной среде. Убедиться в том, что она активирована можно благодаря надписи ( env ) в начале строки приглашения к вводу в терминале.
После этого установите Django и REST Framework в среду:
Создайте новый проект «blog» и новое приложение «api»:
Вам также понадобится пользователь admin для взаимодействия с панелью управления Django и API. Из терминала запустите следующее:
Установите любой пароль (у него должно быть как минимум 8 символов). Если вы введете слишком простой пароль, то можете получить ошибку.
Для настройки, добавьте rest_framework и api в файл конфигурации (blog/blog/settings.py):
Добавление ApiConfig позволит добавлять параметры конфигурации в приложение. Другие настройки для этого руководства не потребуются.
Перейдите по ссылке http://127.0.0.1:8000/admin и войдите в админ-панель сайта. Нажмите на «Users», чтобы увидеть пользователя и добавить новых при необходимости.
Создание API для пользователей
Теперь с пользователем «admin» можно переходить к созданию самого API. Это предоставит доступ только для чтения списку пользователей из списка API-эндпоинтов.
Сериализатор для User
REST Framework Django использует сериализаторы, чтобы переводить наборы запросов и экземпляры моделей в JSON-данные. Сериализация также определяет, какие данные вернет API в ответ на запрос клиента.
По примеру импортируйте модель User из Django вместе с набором сериализаторов из REST Framework Django.
Класс ModelSerializer генерирует поля сериализатора, которые основаны на соответствующих свойствах модели. Это значит, что не нужно вручную указывать все атрибуты для поля сериализации, поскольку они вытягиваются напрямую из модели.
Ознакомиться подробнее с работой ModelSerializer можно на официальном сайте.
Представления для User
Есть несколько способов создавать представления в REST Framework Django. Чтобы получить возможность повторного использования кода и избегать повторений, используйте классовые представления.
Для создания эндпоинта только для чтения, который возвращал бы список пользователей, добавьте следующее в blog/api/views.py:
В первую очередь здесь импортируется generics коллекция представлений, а также модель User и UserSerialized из предыдущего шага. Представление UserList предоставляет доступ только для чтения (через get ) к списку пользователей, а UserDetails — к одному пользователю.
Названия представлений должны быть в следующем формате:
Пути к эндпоинтам будут настроены на следующем шаге.
URL-паттерны
С моделью, сериализатором и набором представлений для User финальным шагом будет создание эндпоинтов (которые в Django называются URL-паттернами) для каждого представления.
В первую очередь добавьте следующее в blog/api/urls.py (этот файл тоже нужно создать):
Функция path создает элемент, который Django использует для показа страницы приложения. Для этого Django в первую очередь ищет нужный элемент с соответствующим URL (например, users/ ) для запрошенного пользователем. После этого он импортирует и вызывает соответствующее представление (то есть, UserList )
Последовательность указывает на целочисленное значение, которое является основным ключом ( pk ). Django захватывает эту часть URL и отправляет в представление в виде аргумента-ключевого слова.
Прежде чем можно будет взаимодействовать с этими URL-паттернами (и теми, которые будут созданы позже) их нужно добавить в проект. Добавьте следующее в blog/blog/urls.py:
Чтобы убедиться, что все элементы работают корректно, перейдите по ссылке http://127.0.0.1:8000/users, чтобы увидеть список пользователей приложения.
В этом руководстве используется графическое представление API из Django REST Framework для демонстрации эндпоинтов. Интерфейс предоставляет элементы аутентификации и формы, имитирующие фронтенд-клиент. Для тестирования API также можно использовать cURL или httpie.
Обратите внимание на то, что значение пользователя admin равно 1 . Можете перейти к нему, открыв для этого http://127.0.0.1:8000/users/1.
Создание API для Post
После базовой настройки можно приступать к созданию полноценного API для блога с эндпоинтами для постов, комментариев и категорий. Начнем с API для Post.
Модель Post
Типы полей соответствуют таковым в реляционных базах данные. Можете ознакомиться со страницей Models на официальном сайте фреймворка.
В этом случае пользователь может иметь много статей, но у поста может быть всего один владелец. Поле owner может быть использовано во фронтенд-приложении для получения пользователя и отображения его имени в качестве автора поста.
Аргумент related_name позволяет задать другое имя доступа к текущей модели ( posts ) вместо стандартного ( post_set ). Список постов будет добавлен в сериализатор User на следующем шаге для завершения отношения многие-к-одному.
Каждый раз при обновлении модели запускайте следующие команды для обновления базы данных:
Позже их можно будет создавать и через графическое представление API.
Также можно выбрать owner среди существующих пользователей. При создании поста в API пользователя выбирать не нужно. Owner будет задан автоматически на основе данных залогиненного пользователя. Это настроим в следующем шаге.
Сериализатор Post
PrimaryKeyRelatedField представляет список публикаций в этом отношении многие-к-одному ( many=True указывает на то, что постов может быть больше чем один).
Если не задать read_only=True поле posts будет иметь права записи по умолчанию. Это значит, что будет возможность вручную задавать список статей, принадлежащих пользователю при его создании. Вряд ли это желаемое поведение.
Перейдите по ссылке http://127.0.0.1:8000/users, чтобы увидеть поле posts каждого пользователя.
Django Rest Framework для начинающих: создаём API для чтения данных (часть 1)
Меня зовут Стас Гаранжа, я выпускник курса «Python-разработчик» в Яндекс.Практикуме. Я хочу помочь начинающим разработчикам, которые приступили к изучению Django Rest Framework (DRF) и хотят разобраться, как устроен этот фреймворк.
Я готовлю цикл статей, в которых расскажу о разных сторонах работы DRF. У меня пока нет значимого практического опыта для описания всех изюминок при работе с этим фреймворком, поэтому в основе статьи — исследование, обобщение и по возможности непротиворечивое изложение того, что у DRF под капотом.
В этой статье разберёмся, как сделать REST API на базе Django Rest Framework, чтобы получить по GET-запросу набор записей из базы данных (БД). Иными словами, рассмотрим, как DRF работает на чтение (о том, как с помощью него создавать, изменять и удалять записи в БД, поговорим в отдельной статье).
Общую схему решения этой задачи мы рассмотрим в первой части статьи. Вторая будет посвящена детальному разбору процесса сериализации данных.
Несколько вводных замечаний:
Надеюсь, статья станет хорошим подспорьем изучения DRF и работы с его документацией, прояснит процесс сериализации данных и даст уверенность, что любая магия исчезает, стоит только покопаться под капотом конкретной библиотеки.
API для сайта на Django: общая схема
Задача
На локальном сервере работает одностраничный сайт на Django. На единственной странице сайта по адресу http://localhost:8000 пользователи видят информацию о четырёх североевропейских столицах. Информация попадает на страницу из подключённой к сайту базы данных, в которой есть модель Capital с пятью полями:
| id | country | capital_city | capital_population | author (FK) |
|---|---|---|---|---|
| 1 | Norway | Oslo | 693500 | 1 |
| 2 | Sweden | Stockholm | 961600 | 1 |
| 3 | Finland | Helsinki | 655300 | 1 |
| 4 | Iceland | Reykjavik | 128800 | 1 |
Поле author через внешний ключ (foreign key) связано с моделью User, в которой есть вся информация о пользователе с конкретным id.
Мы хотим получить информацию из базы данных, не открывая сайт в браузере, а сделав запрос из другого Python-приложения.
В каком виде нужно получить информацию:
Таким образом, каждую запись, которая при извлечении из базы данных является Python-объектом, принимающее приложение после декодирования json-строки должно получать в виде словаря:
В этом и состоит одно из назначений API — дать возможность различным приложениям доставать из БД сайта информацию в виде структуры данных, которую дальше можно обрабатывать.
Решаем задачу с помощью Django Rest Framework
Задача решается в два шага:
Небольшое отступление о json. Базовые структуры данных на python кодируются в json и декодируются обратно следующим образом:
| Python | JSON | Пример Python | Пример JSON |
|---|---|---|---|
| dict | object | ||
| list, tuple | array | [‘элемент1’, ‘элемент2’], (‘элемент1’, ‘элемент2’) | [«элемент1», «элемент2»] |
| str | string | ‘элемент1’ | «элемент1» |
| int, float, int- & float-derived Enums | number | 5, 4.2 | 5, 4.2 |
| True | true | True | true |
| False | false | False | false |
| None | null | None | null |
Создаём сериалайзер
Для сериалайзера нужно описать поля: каждое поле будет отвечать за извлечение и представление данных из корреспондирующего поля табличной записи.
Нас интересуют данные, которые есть в трёх полях каждой табличной записи:
Значит, в сериалайзере должно быть тоже три атрибута-поля.
При создании поля сериалайзера нужно определиться с названием поля и его типом. Назвать поля сериалайзера можно как угодно: именно эти названия будут ключами в словаре, в который сериалайзер преобразует запись из таблицы.
Вот примеры трёх вариантов названий полей сериалайзера:
Очевидно, этот тип поля сериалайзера нельзя выбирать для данных из табличной записи о названии столицы: int(‘Осло’) вызовет ValueError. А вот для данных о численности населения — самое то.
Выберем следующие типы полей сериалайзера:
| Название поля в таблице (модели) | Тип поля в таблице (модели) | Тип корреспондирующего поля сериалайзера |
|---|---|---|
| capital_city | models.CharField | serializers.CharField |
| capital_population | models.IntegerField | serializers.IntegerField |
| author | models.ForeignKey | serializers.CharField |
О соотношении полей сериалайзера и полей Django-моделей можно прочитать в документации DRF.
Код сериалайзера разместим в том же приложении, где находится Django-модель, под именем serializers.py:
Сериалайзер в действии
В serializer_example_1.py созданы классы с данными об авторах и о столицах для записей в таблицах:
Созданы объекты соответствующих записей:
Объединены записи в список по подобию кверисета из Django-модели:
Выведем в консоль содержимое атрибута data сериалайзера:
В каждом OrderedDict содержится информация только из тех полей табличных записей, которые были состыкованы с полями сериалайзера. Данных о содержимом поля country нет — сериалайзер не настроен доставать эту информацию, потому что мы не создавали корреспондирующего поля в сериалайзере.
Отображаем (рендерим) информацию в формате json
Далее необходимо создать экземпляр рендера нужного типа и вызвать у него метод render :
В результате мы увидим байтовую строку с массивом json-объектов:
Что нужно ещё
Итак, мы испытали сериалайзер и посмотрели, как пропущенный через него набор табличных записей был преобразован в json-формат.
Чтобы сайт начал отдавать сериализованные данные, остаётся описать контроллер (view) и указать url-маршрут — эндпоинт, при обращении к которому сайт будет отдавать данные о столичных городах.
Контроллер
Во views.py создадим класс контроллера. Нам понадобятся следующие инструменты DRF:
Внутри контроллера описываем один метод — get. Почему он называется именно так?
Пример: если поступил GET-запрос, то будет задействован метод get контроллера.
В методе get опишем ту же логику, что и в файле с пробным запуском сериалайзера:
После того как отработал метод get, работа контроллера выглядит так:
Маршрут (эндпоинт)
Здесь та же схема действий, как в классическом Django. Подключаем маршруты приложения capitals:
Прописываем сам маршрут в приложении capitals и связываем маршрут с контроллером:
API в действии
Чтобы посмотреть, как работает API, можно:
Осталось выполнить шаги 2 и 3.
Если всё отработало штатно, в корневой директории проекта появится файл capitals.txt со следующим содержимым:
Несмотря на то, что пример наивный, он показывает главное: как мы научили
веб-приложение отдавать информацию из базы данных в ответ на запрос, который поступает не от человека через браузер, а от другого приложения. И далее — как это приложение использует полученную информацию.
Browsable API — удобный инструмент для тестирования API на DRF
Django Rest Framework позволяет посмотреть в браузере, какую информацию будет отдавать API при обращении к конкретному маршруту (эндпоинту). Достаточно ввести маршрут в адресную строку, и откроется страница с данными о запросе и результате его выполнения. За такое отображение отвечает BrowsableAPIRenderer.
Итак, мы рассмотрели, как сделать API на базе DRF, чтобы получить по GET-запросу набор записей из Django-модели. Во второй части подробно разберём работу сериалайзера на чтение.
Если у вас появились вопросы по решению задачи, пишите в комментариях.
