PDFer: создаем PDF документы легко.

Троеглазов Андрей

Правильное REST API.В D8.

Evgeny Yudkin

Evgeny Yudkin

Drupal developerTechnical leader

● 3 years in development;● Drupal contributor;● Drupal audit;● Working under API using D8.

● API;● Инструменты;● Подходы;● REST;● Реализация в D8.

О чём эта презентация?

● Мобильные приложения;● Фронтенд;● Другие сервисы нашего приложения (микросервисная

архитектура);● Сторонние приложения (публичное API).

API

Архитектура:API-first

Пользователи

Фронтенд

Представление

Бизнес-логика

База данных

API HTMLВсе этапы на каждый запрос(“толстый сервер”)

Classic

API-firstПользователи

Фронтенд

Представление

База данных

HTML

Бизнес-логика

“Мобильные”пользователи

API API“тонкий сервер”

API-first

REST

● RESTful - это дизайн API;● Про понятность;● Некий стандарт;● Полностью 100%-но никто не поддерживает;● Но существуют BEST Practices и паттерны;

REST? RESTful?

● В основе REST лежит концепция разделения структуры API на логические ресурсы, не связанные с представлением данных внутри приложения;

● Основывается на HTTP;● Переиспользует существующие стандарты и

фишечки.

REST? RESTful?

● /cars - список машин;● /cars/1 - конкретная машина;● /cars/1/drivers - список водителей;● /cars?color=red - поиск машины по цвету.

Пример

● Клиент-серверная архитектура;● Cервер не хранит состояние (Stateless);● Кэшируемость;● Многослойная структура;● Единый интерфейс;● Код по требованию (опционально).

REST? RESTful?

● Рест оперирует ресурсами;● Ресурсы могут быть связаны между собой;

Ресурсы

Готовим REST правильно

● Не привязываемся к структуре сущностей в приложении/cars вместо /node;

● Используем http-методы○ GET - для получения;○ POST или PUT - для создания;○ PATCH - для модификации;○ DELETE - для удаления;

Делаем правильно

● Используем конкретные имена вместо абстрактных○ /items - зло;

● Для сущностей, а не действий - используем существительные○ /getAllCars - плохо;

● GET’ы - “безопасны” и ничего не меняют;● Для связей используем под-ресурсы:

○ /cars/1/drivers● Для определения формата используем заголовки:

○ Content-Type○ Accept

Делаем правильно

● Фильтрация;● Сортировка;● Пагинация;● Частичные ответы;

Делаем правильно

● Используем http-статусы;● Для ошибок возвращаем полезную нагрузку;● Идемпотентность всего, кроме POST;

Делаем правильно

Инструменты

● POST

○ Если API само должно вернуть идентификатор объекта;○ Дубликаты.

● PUT

○ Если мы знаем урл (идентификатор) создаваемого объекта;○ Идемпотентность.

REST: POST vs PUT

● Определение

○ Через URL: /api/v1/something;○ Через User Agent или другие

заголовки/параметры запроса;

● Изменения○ Глобальные изменения (бизнес-логика)

■ Новый код;

○ Изменения формата■ Изменения в выводе;

Версионирование

Бизнес-логика

Определение версии API

Запрос

Формат 1 Формат 2

Ответ

● Hypermedia as the Engine of Application State;

О чём это?

● В каждом полученном ответе содержится ссылка на следующий запрос.

Гипертекст и HATEOAS

HAL

● Hypertext Application Language

{ "_links": { "self": { "href": "http://example.org/api/user/matthew" } }, "id": "matthew", "name": "Matthew Weier O'Phinney"}

{ "_links":{ "self":{ "href":"http:\/\/dev.ru\/node\/4?_format=hal_json" }, "type":{ "href":"http:\/\/dev.ru\/rest\/type\/node\/page" }, "http:\/\/dev.ru\/rest\/relation\/node\/page\/field_article":[ { "href":"http:\/\/dev.ru\/node\/3?_format=hal_json" } ] }, ….}

● Модель срока действия;● Модель валидности;

○ ETag;○ Last-Modified;

Кэширование

Drupal 8

● REST-плагины;● RestResponce;● Нет обработки ошибок;● Настройка “по ресурсу” и “по verb’u”:

○ Аутентификация;○ Пермишены;○ Формат;

● Множество ресурсов “по умолчанию”:○ Универсальный для любой content entity;

REST module

● Предоставляет возможность создавать endpoint’ы;● Можно прикреплять к endpoint’ам ресурсы и настраивать их;

● Например: /v1/node/{node}

Services module

● JSON API○ Стандарт;○ Формат - JSON;○ Не hal_json, но при этом поддерживает hal;

JSONAPI

● Модуль○ Предоставляет набор ресурсов “по умолчанию”, включая

универсальный;○ Предоставляет коллекции;○ Нет UI;○ Не связан с модулем REST;○ Нет настройки “по ресурсу”;○ Сложности с кастомными ресурсами;○ Нестабилен при работе с file_entity и другими кастомными

нормализаторами;

JSONAPI module

● Связан с REST;● Предоставляет несколько REST-ресурсов для получения данных о

структуре сущностей;● Нужен для работы одноименных фронтенд-библиотек.

WATERWHEEL module

● Является частью DrupalDeploy;● Зависим от REST;● Предоставляет улучшенную поддержку:

○ Ревизионности;○ Мультиязычности;○ Связями через uuid;○ Работы с файлами;

■ Multipart;

RELAXED module

● Формально с REST не связан;● Превращает файлы в сущности с возможностью добавлять поля;● Эти сущности можно создавать через REST;● Предоставляет нормалайзеры для работы с контентом файлов в

base64;● Нормалайзеры работают только с hal_json.

FILE_ENTITY module

Evgeny Yudkin

Drupal developeryudkin.e@i20.biz При поддержке:

Организаторы:

Thank you!