REST-архитектура #

Васильев Андрей Михайлович, 2024

Версии презентации

Реализация распределённых приложений #

Как организовать связь между удалёнными системами?
Как обратиться к удалённой системе?
В каком виде формировать запросы к системе?
Как должен быть устроен клиент, чтобы выполнить запрос?

Существует множество технологий, которые позволяют решить данную задачу: REST, SOAP, gRPC и т.д.

Рассмотрим в качестве технологии описания маршрутов REST:

Является достаточно распространённой
Основана на использовании особенностей протокола HTTP
Обычно использует JSON как средство передачи данных

REST #

REST — акроним Representational State Transfer, передача репрезнтативного состояния

Представляет собой некоторый набор рекомендаций, которым может следовать HTTP-сервер для предоставления возможностей удалённому клиенту

Не является точной спецификацей
Правила разработаны одним из создателей протокола HTTP
Службы, соответствующие правилам, называются RESTful

Правила REST #

Отделение клиента от сервера #

Код запросов формируется на клиенте, а код по обработке запроса — на стороне сервера

Позволяет независимо менять реализации сервера, реализовывать множество независимых клиентов

Отсутствие записи состояния клиента #

Сервер не хранит информацию о текущем состоянии (или списке операций) клиента

Клиент должен передаёт все данные, которые нужны для выполнения запроса

Кэширование #

Сервер может пометить, что результат запроса может быть закеширован на клиенте, таким образом может быть уменьшено число запросов

Например справочник названий населённых пунктов не будет часто меняться

Единообразие интерфейса #

Обращение к ресурсам сервера должно быть выстроено на единых принципах

Данные передаются по протоколу HTTP
В качестве данных ответа всегда возвращается JSON или XML

Многоуровневость системы #

Сервер может быть организован достаточно сложно, но клиенты (даже в рамках сервера) всегда взаимодействуют с одним конкретным сервером, который может уже далее выполнять свои запросы для решения задачи

Код по требованию #

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

Не является обязательным для реализации

Сетевые ресурсы #

REST не определяет никаких методов для доступа к удалённым ресурсам, вместо этого применяется комбинация из других протоколов: HTTP, URI, JSON и XML

При формировании серверов, предоставляющих доступ к данным с помощью REST рекомендуется следовать правилам, ориентированным на ресурсы

Ресурс — это часть данных, например данные о пользователе
Коллекция — это группа ресурсов, например список пользователей
URI определяет местоположение ресурса или коллекции, например /users
Операции над ресурсами определяются с помощью методов протокола HTTP
Результат выполнения операции описывается с помощью кодов ответа HTTP

Методы HTTP #

Над сетевыми ресурсами можно выполнять операции создания, чтения, модификации и удаления (анг. CRUD), данные операции удобно описываются с помощью HTTP-методов:

POST — создание нового ресурса
GET — получение существующего ресурса
PUT — обновление существующего ресурса
PATCH — частичное обновление путём обновления полей ресурса
DELETE — удаление существующего ресурса

Запросы на изменение данных на сервере (POST, PUT, PATCH, DELETE)

Не должны кэшироваться на промежуточных серверах
Передают данные в основном в теле запроса, а не в параметрах

Если необходимо выполнить операцию, изменяющую состояние на сервере, и не входящую в набор CRUD, необходимо использовать POST-запрос

Описание путей к ресурсам #

Из описания пути должно быть понятно количество ресурсов по пути:

Для одиночного ресурса используйте единственное число: /profile
Для коллекции используйте множественное число:
- /users для получения всего списка
- /users/{userId} для получения элемента из списка по идентификатору
Рекомендуется всегда начинать путь с ресурса, а заканчивать идентификатором

Примеры запросов

GET /courses/5/classes — получить список предметов у 5-го курса
DELETE /courses/4/classes/2 — удалить предмет 2 у 4-го курса
POST /courses — создать новый курс и получить его идентификатор
PUT /courses/6 — обновить данные для 6-го курса

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

Любые серверные приложения со временем развиваются, в них появляется новая функциональность, а старая функциональность становится не актуальной, либо сложной в поддержании

Соответственно на самом верхнем уровне рекомендуется добавлять явный номер:

/v1/users/
/v2/courses

Таким образом разработчик может ввести новый API, предоставляя возможность клиентам перейти на новый API:

Сначала вводится новый API в экспериментальном режиме
Затем он стабилизируется, изменения после этого должны быть обратно совместимы
Старый интерфейс помечается как устаревший, клиентам рекомендуется перейти на новую версию
По прошествии времени старый интерфейс убирается из системы

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

В оригинальном предложении относительно REST-архитектуры предлагалось возвращать документы, в которых явно отображены действия, которые пользователь может сделать

При работе с гипертекстом (HTML) так и происходит, т.к. пользователь видит интерактивные элементы и может выбрать действие для своего выполнения

При возвращении JSON-документов не сложилась практика по предоставлению этой информации внутри самих документов
Рекомендуется предоставлять документацию клиентам в одном из общепринятых стандартов: API Blueprint, Open API и т.д

Тестирование REST-приложений #

Для выполнения сквозного тестирования (end-to-end) можно воспользоваться

Самостоятельно написанными инструментами, http4k позволяет легко описать последовательность клиентских запросов
Воспользоваться существующими инструментами
- Приложения с командным интерфейсом: curl, Hurl, HTTPie и т.д
- Приложения с графическим интерфейсом: Postman, Bruno и т.д.
- Расширения или встроенные средства сред разработки
При наличии описания в одном из стандартных форматах, можно воспользоваться соответствующими инструментами, которые могут использовать эти данные для выполнения тестирования