О чем стоит помнить при проектировании REST API

Давайте вспомним, что такое REST API и с чем его едят.

Теория REst api

REST API - это один из архитектурных стилей взаимодействия компонентов или сервисов распределенной системы. Не пугайтесь словосочетания "архитектурный стиль" - на самом деле это просто набор ограничений и правил проектирования, с помощью которого можно добиться определенных целей.

А целей у REST API аж 5: система должна быть производительной, масштабируемой, гибкой, отказоустойчивой и простой в поддержке. Для получения этих свойств нужно следовать шести принципам REST API.

Принципы REST:
  • Единый интерфейс. К каждому ресурсу должен быть единый способ обращения, логика должна быть такой же, как и раньше. Для реализации единого интерфейса используется подход HATEOAS (Hypermedia as the Engine of Application State);
  • Разграничение клиента и сервера. Обычно на клиенте реализована функциональная часть, а на сервере - хранение данных, интеграции и прочие низкоуровневые трюки. Это свойство позволяет добиться масштабируемости;
  • Нет сохранения состояния. Если информацию о каждом запросе будет сохранять сервер, то это приведет к невозможности масштабирования и клонирования. Такую информацию должен хранить клиент;
  • Кэширование всегда разрешено. Полезно, когда у сервера запрашивают одинаковую информацию - при кэшировании уменьшается количество сетевых взаимодействий и, как следствие, нагрузка на систему;
  • Многоуровневая система. Этот относится к структуре сервера и предполагает использование дополнительных серверов-балансировщиков, выполняющих роль промежуточных узлов. Используются для кэширования, безопасности и дополнительной обработки данных;
  • Код предоставляется по запросу. Необязательный принцип, по которому сервер в ответ на запрос отправляет некоторый исходный код (например, на отрисовку элементов пользовательского интерфейса).

Когда применяют REST:
  • При ограниченной пропускной способности соединения с сервером
  • Нужно кэшировать запросы
  • При масштабировании сайта/приложения
  • Если сайт/приложение используют AJAX

АРХИТЕКТУРА REST API

Архитектура REST API состоит из четырех компонентов:
  1. URL-адрес конечной точки. Приложение с REST API определяет один или несколько URL-адресов конечных точек с доменом, порт, путь, строки запроса;
  2. Метод HTTP. Есть 5 методов: GET (получение), POST (размещение), PUT (полное обновление), PATCH (частичное обновление), DELETE (удаление);
  3. Заголовки HTTP. Содержат токены аутентификации или файлы cookie;
  4. Body. Данные передаются в теле HTTP идентично HTML-представлению.

Первые два компонента разберем на примере следующей строки:

GET https://api.openweathermap.org/data/2.5/weather


GET - это метод для получения, с его помощью мы получим некоторые данные. В самой строке есть HTTPS (протокол), api.openweathermap.org (ресурс или хост), и data/2.5/weather (путь), все вместе это образует URL - адрес конечной точки. Таким образом, с помощью этой строки мы получим информацию о погоде (температура, давление и др.), данные в ответе уже определены на уровне сервера.

Остальные два компонента определяют, что содержит в себе запрос. Например:

POST /orders

{

"name": "Julia",

"date": "25.03.2023",

"product": "laptop"

}


Часть примера, выделенная фигурными скобками, является телом (body) запроса. С помощью этого запроса мы скажем серверу, что нужно записать (POST) информацию о том, что клиент купил ноутбук 25 марта 2023 года.

Вот еще пару примеров посложнее:
На данном примере вы можете увидеть, как загрузить прикрепленный файл с определенной страницы (где 1998856 ID контента).
Добавление коммента на страницу
Ссылка на загрузку внутри аутпута

При проектировании API стоит помнить о:

Следуя следующим простым правилам, вы сможете спроектировать качественный API, который оставит хорошее впечатление о продукте, и, как следствие, о вас в роли системного аналитика тоже.
  • API должен быть предсказуемым
  • Унифицированные методы авторизации и аутентификации для всех конечных точек
  • Одинаковые методы HTTP для одних и тех же действий
  • Единый регистр для полей, ресурсов и параметров
  • Все имена ресурсов должны быть в множественном или единственном числе /orders/{id} или /order/{id}
  • Коды состояний HTTP должны быть одинаковы в зависимости от типа ответа (если страница не найдена, всегда 404)
  • Одинаковые методы HTTP для одних и тех же действий
  • Проверяйте работоспособность конечной точки
  • При каждом запросе передавайте версию API
  • Аутентификация принимается по ключу API
  • Проверяйте коды состояния HTTP на соответствие при использовании
  • Используйте простые имена, которые легко понять
  • При возврате ошибки пользуйтесь стандартным ответом об ошибке
  • Максимальная конкретика во всем (разработка конечных точек, имя и описание полей и тп)
Практический опыт по API
Вы можете получить на нашем курсе