# Настройка API --- ## Что такое API ---- Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). ---- Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина». ---- WWW можно представить как огромную сеть связанных серверов, на которых и хранится каждая страница. ---- При введении в адресную строку браузера `www.facebook.com` на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу. ---- Каждый раз, когда пользователь посещает какую-либо страницу в сети, он взаимодействует с API удалённого сервера. API — это составляющая часть сервера, которая получает запросы и отправляет ответы. ---- Чем API отличается от привычных нам методов? Разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON. ---- Пользователь благодаря API получает возможность совершить действие, не покидая сайт компании. ---- Многие разработчики разносят приложение на несколько серверов, которые взаимодействуют между собой при помощи API. Серверы, которые выполняют вспомогательную функцию по отношению к главному серверу приложения, называются микросервисами. ---- Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает: * фрагмент программного обеспечения с определённой функцией, * сервер целиком, приложение целиком или же просто отдельную часть приложения. --- ## Вызов API напрямую ---- ### Система вызывает функции внутри себя Разные части программы как-то общаются между собой. Они делают это на программном уровне, то есть на уровне API! Это самый «простой» в использовании способ, потому что автор API, которое вызывается — разработчик. ---- ### Система вызывает метод другой системы Одна система дергает через api какой-то метод другой системы. Она может попытаться получить данные из другой системы. Или наоборот, отправить данные в эту систему. ---- ### Человек вызывает метод Причины разные: * Для ускорения работы * Для локализации бага (проблема где? На сервере или клиенте?) * Для проверки логики без докруток фронта Если система предоставляет API, обычно проще дернуть его, чем делать то же самое через графический интерфейс. Тем более что вызов API можно сохранить в инструменте. Один раз сохранил — на любой базе применяешь, пусть даже она по 10 раз в день чистится. ---- ### Косвенный вызов API Когда пользователь работает с GUI, на самом деле он тоже работает с API. Просто не знает об этом, ему это просто не нужно. То есть когда пользователь открывает систему и пытается загрузить отчет, ему не важно, как работает система, какой там magic внутри. У него есть кнопочка «загрузить отчет», на которую он и нажимает. Пользователь работает через GUI (графический пользовательский интерфейс). --- ## Как работает Django REST framework ---- Django Rest Framework (DRF) — это библиотека, которая работает со стандартными моделями Django для создания гибкого и мощного API для проекта. ---- API DRF состоит из 3-х слоев: сериализатора, вида и маршрутизатора. * Сериализатор * Вид (ViewSet) * Маршрутизатор ---- Модели Django интуитивно представляют данные, хранящиеся в базе, но API должен передавать информацию в менее сложной структуре. Хотя данные будут представлены как экземпляры классов Model, их необходимо перевести в формат JSON для передачи через API. ---- Сериализатор DRF производит это преобразование. Когда пользователь передает информацию (например, создание нового экземпляра) через API, сериализатор берет данные, проверяет их и преобразует в нечто, что Django может сложить в экземпляр модели. ---- Наиболее распространенной формой, которую принимает сериализатор DRF, является тот, который привязан непосредственно к модели Django: ``` class ThingSerializer(serializers.ModelSerializer): class Meta: model = Thing fields = ('name', ) ``` ---- Сериализатор анализирует информацию в обоих направлениях (чтение и запись), тогда как ViewSet - это тот код, в котором определены доступные операции. ---- Наиболее распространенным ViewSet является ModelViewSet, который имеет следующие встроенные операции: Создание экземпляра: create() Получение / чтение экземпляра: retrieve() Обновление экземпляра (все или только выбранные поля): update() или partial_update() Уничтожение / Удаление экземпляра: destroy() Список экземпляров (с разбивкой по страницам по умолчанию): list() ---- Каждая из этих функций может быть переопределена, если требуется другое поведение, но стандартная функциональность работает с минимальным кодом, а именно: ``` class ThingViewSet(viewsets.ModelViewSet): queryset = Thing.objects.all() ``` ---- И наконец, маршрутизаторы: они предоставляют верхний уровень API. ---- тобы избежать создания бесконечных URL-адресов вида: «списки», «детали» и «изменить», маршрутизаторы DRF объединяют все URL-адреса, необходимые для данного вида в одну строку для каждого ViewSet, например: ``` # Инициализация роутера DRF. Только один раз на файл urls.py # из маршрутизаторов импорта rest_framework router = routers.DefaultRouter() # Регистрация ViewSet router.register(r'thing', main_api.ThingViewSet) ``` ---- Затем все ViewSet, которые зарегистрированны в маршрутизаторе, можно добавить к обычным url_patterns: `<kbd>url_patterns + = url (r '^', include (router.urls))</kbd>` Теперь через API можно получить данные точно так же, как и любые другие обычные страницы Django. --- ## Настройка API в приложении ---- Установим библиотеки Django REST framework и django-cors-headers, для чего наберем команды: ``` pip install djangorestframework pip install django-cors-headers ``` ---- Сразу же создадим новое приложение api, в котором и реализуем функциональность веб-службы: `python manage.py startapp api` ---- Добавим приложения rest_framework И corsheaders — Программные Ядра ТОЛЬКО что установленных библиотек, а также только что созданное приложение api в список зарегистрированных в проекте: ``` INSTALLED_APPS = [ ... 'rest_framework', 'corsheaders', 'api.apps.ApiConfig', ] ``` ---- Добавим в список зарегистрированных в проекте необходимый для работы посредник: ``` MIDDLEWARE = [ 'corsheaders.middleware.CorsMiddleware', 'django.middleware.common.CommonMiddleware', ] ``` ---- He забудем указать там же, в модуле settings.py пакета конфигурации, настройки, разрешающие доступ к веб-службе с любого домена: ``` CORS_ORIGIN_ALLOW_ALL = True CORS_URLS_REGEX = r'^/api/.*$' ``` ---- Создадим в пакете приложения api модуль serializers.py. В нем сохраним код сериализатора BbSerializer, формирующего список объявлений. ``` from rest_framework import serializers from main.models import Bb class BbSerializer(serializers.ModelSerializer): class Meta: model = Bb fields = ('id', 'title', 'content', 'price', 'created_at') ``` ---- онтроллер, который будет выдавать список объявлений, реализуем в виде функции и назовем bbs(). ``` from rest_framework.response import Response from rest_framework.decorators import api_view from main.models import Bb from .serializers import BbSerializer @api_view(['GET']) def bbs(request): if request.method == 'GET': bbs = Bb.objects.filter(is_active=True)[:10] serializer = BbSerializer(bbs, many=True) return Response(serializer.data) ``` ---- Откроем список маршрутов уровня проекта (модуль urls.py пакета конфигурации) и добавим маршрут, указывающий на приложение api: ``` urlpatterns = [ ... path('api/', include('api.urls')), path('', include('main.urls')), ] ``` ---- В пакете приложения api создадим модель urls.py, в который запишем список маршрутов уровня этого приложения. ``` from django.urls import path from .views import bbs urlpatterns = [ path('bbs/', bbs), ] ``` ---- Сохраним код, запустим отладочный веб-сервер и попробуем получить список объявлений, перейдя по интернет-адресу `http://localhost:8000/api/bbs/`. Если мы все сделали правильно, то увидим веб-представление, показывающее последние 10 объявлений, которые были оставлены посетителями сайта. ---- Занесем код сериализатора BbDetaiiserializer, выдающего сведения об объявлении в модуль serializers.py пакета приложения. ``` class BbDetailSerializer(serializers.ModelSerializer): class Meta: model = Bb fields = ('id', 'title', 'content', 'price', 'created_at', 'contacts', 'image') ``` ---- Контроллер назовем BbDetailView и реализуем в виде класса, производного от класса RetrieveAPIView. Его код, весьма компактный. ``` from rest_framework.generics import RetrieveAPIView from .serializers import BbDetailSerializer class BbDetailView(RetrieveAPIView): queryset = Bb.objects.filter(is_active=True) serializer_class = BbDetailSerializer ``` ---- Добавим в список маршрутов уровня приложения маршрут, который укажет на наш новый контроллер: ``` from .views import BbDetailView urlpatterns = [ path('bbs/<int:pk>/', BbDetailView.as_view()), path('bbs/', bbs), ] ``` ---- Код сериализатора Commentserializer, который будет отправлять список комментариев и добавлять новый комментарий. ``` from main.models import Comment class CommentSerializer(serializers.ModelSerializer): class Meta: model = Comment fields = ('bb', 'author', 'content', 'created_at') ``` ---- од контроллера-функции comments(), выдающего список комментариев и добавляющего новый комментарий. ``` from rest_framework.decorators import permission_classes from rest_framework.status import HTTP_201_CREATED, HTTP_400_BAD_REQUEST from rest_framework.permissions import IsAuthenticatedOrReadOnly from main.models import Comment from .serializers import CommentSerializer @api_view(['GET', 'POST']) @permission_classes((IsAuthenticatedOrReadOnly,)) def comments(request, pk): if request.method == 'POST': serializer = CommentSerializer(data=request.data) if serializer.is_valid(): serializer.save() return Response(serializer.data, status=HTTP_201_CREATED) else: return Response(serializer.errors, status=HTTP_400_BAD_REQUEST) else: comments = Comment.objects.filter(is_active=True, bb=pk) serializer = CommentSerializer(comments, many=True) return Response(serializer.data) ``` ---- Маршрут, который укажет на новый контроллер и который мы поместим в список уровня приложения, будет выглядеть так: ``` from .views import comments urlpatterns = [ path('bbs/<int:pk>/comments/' , comments), path('bbs/<int:pk>/', BbDetailView.as_view()), ] ```