Что такое REST API?
2026-02-26 15:13 Diff
https://ru.hexlet.io/blog/posts/rest-api

REST API это HTTP API (иногда говорят WEB API) построенный по принципам REST-архитектуры. Впервые термин REST ввел Рой Филдинг в своей докторской диссертации "Architectural Styles and the Design of Network-based Software Architectures" в 2000 году. Многие обратили на нее серьезное внимание, потому что Рой был не случайным человеком в индустрии. Этот ученый был одним из ключевых разработчиков протокола HTTP/1.0 и автором HTTP/1.1. Он участвовал в разработке языка HTML и стандарта URI. Кроме того, он соавтор некогда самого популярного веб-сервера в мире Apache Web Server.

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

Содержание

Немного истории

Прежде чем обсуждать конкретно, что из себя представляют принципы REST, нужно немного поговорить о его истории. Глобально, REST это не про то как делать HTTP API. REST это, то по каким принципам должен был быть построен весь WEB.

Since 1994, the REST architectural style has been used to guide the design and development of the architecture for the modern Web. This work was done in conjunction with my authoring of the Internet standards for the Hypertext Transfer Protocol (HTTP) and Uniform Resource Identifiers (URI), the two specifications that define the generic interface used by all component interactions on the Web.

— Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, p. 107.

То есть не REST появился для того чтобы упорядочить WEB, а WEB стал таким чтобы соответствовать REST.

Термин "REST" был введён Роем Филдингом, одним из создателей протокола "HTTP", лишь в 2000 году. В своей диссертации "Архитектурные стили и дизайн сетевых программных архитектур" ("Architectural Styles and the Design of Network-based Software Architectures") в Калифорнийском университете в Ирвайне он подвёл теоретическую основу под способ взаимодействия клиентов и серверов во Всемирной паутине, абстрагировав его и назвав "передачей представительного состояния".

Чтобы протокол взаимодействия соответствовал REST-стилю, необходимо соблюсти, как минимум, 5 требований. Если сервис соблюдает только часть из них, то про такой протокол говорят, что он REST-like. Если соблюдаются все требования, то протокол является RESTful. На практике, есть ситуации, в которых невозможно следовать REST требованиям, поэтому большинство протоколов являются REST-like, даже если они утверждают другое.

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

  1. Идентификация. В отличие от RPC, в котором протоколы ориентированы на действия, в REST стиле подразумевается ориентация на ресурсы (существительное). Взаимодействие с каждым ресурсом происходит посредством представлений ресурса, запрашиваемых по URN, который идентифицирует конкретный ресурс. То есть, мы никогда не взаимодействуем с самим ресурсом напрямую, а получаем лишь его представления, которых может быть много. Сервер может отдать данные в формате json или html, хотя при этом ни один из них не является реальным типом хранения внутри сервера.
  2. Манипуляция ресурсами через представление. Если клиент хранит представление ресурса, включая метаданные - он имеет достаточно данных для модификации или удаления ресурса.
  3. "Самоописываемые" сообщения. Каждое сообщение содержит достаточно информации, чтобы описать, каким образом его обрабатывать. К примеру, какой парсер необходимо применить для извлечения данных, может быть описано в Internet медиа-типе, другими словами, посылая на сервер json в теле http запроса, REST диктует обязательную установку типа контента в заголовке. В общем случае для обработки сообщения должно быть достаточно информации из самого сообщения (всё, что может передаваться по http).

По таблице ниже видно, что каждый URN является идентификатором либо одиночного ресурса, либо коллекции ресурсов (это тоже ресурс), а необходимые действия задаются посредством использования подходящего http метода. И всё это должно происходить в строгом соответствии семантике http, другими словами, REST использует то, что заложено в http, а не меняет это или добавляет свое.

Кэширование

Как и во Всемирной паутине, каждый из клиентов, а также промежуточные узлы между сервером и клиентами могут кэшировать ответы сервера. В каждом запросе клиента должно явно содержаться указание о возможности кэширования ответа и получения ответа из существующего кэша. В свою очередь, ответы могут явно или неявно определяться как кэшируемые или некэшируемые для предотвращения повторного использования клиентами в последующих запросах сохранённой информации. Правильное использование кэширования в REST-архитектуре устраняет избыточные клиент-серверные взаимодействия, что улучшает скорость и расширяемость системы.

Отсутствие состояния

Протокол взаимодействия между клиентом и сервером не сохраняет какого-либо сессионного состояния после запроса и ответа (Stateless protocol). В случае необходимости, такое состояние должно сохраняться на клиенте. Только тогда пользователь отвязан от конкретного сервера, что, в свою очередь, позволяет масштабироваться и безболезненно переносить (балансировать) запросы между серверами.

Примером такого состояния является корзина в интернет магазине. Если она привязана к пользовательской сессии и хранится на конкретном сервере (а не в браузере клиента), то отправить запрос пользователя на другой сервер станет невозможно. Он просто не увидит своей корзины. Эту проблему можно решить двумя способами. Первый - хранить её на клиенте, используя, например, cookie. Вторая - изменением способа хранения корзины на сервере и помещением её в базу данных, которая доступна со всех серверов.

На практике сайты активно используют понятие "сессии", при котором данные могут храниться на стороне сервера, что является нарушением REST.

Клиент-серверная архитектура

Разграничение потребностей является принципом, лежащим в основе данного накладываемого ограничения. При отделении потребностей интерфейса клиента от потребностей сервера, хранящего данные, повышается переносимость кода клиентского интерфейса на другие платформы, а при упрощении серверной части улучшается масштабируемость.

Слои

Клиент может взаимодействовать не напрямую с сервером, а через промежуточные узлы (слои). При этом клиент может не знать об их существовании, за исключением случаев передачи конфиденциальной информации. Промежуточные серверы выполняют балансировку нагрузки и могут использовать дополнительное кэширование.

Код по требованию (необязательное ограничение)

REST может позволить расширить функциональность клиента за счёт загрузки кода с сервера в виде апплетов или сценариев. Филдинг утверждает, что дополнительное ограничение позволяет проектировать архитектуру, поддерживающую желаемую функциональность в общем случае, но возможно за исключением некоторых контекстов.

Преимущества REST

Филдинг указывал, что приложения, не соответствующие приведённым условиям, не могут называться REST-приложениями. Если же все условия соблюдены, то, по его мнению, приложение получит следующие преимущества:

  • Надёжность (за счёт отсутствия необходимости сохранять информацию о состоянии клиента, которая может быть утеряна)
  • Производительность (за счёт использования кэша)
  • Масштабируемость
  • Прозрачность системы взаимодействия (особенно необходимая для приложений обслуживания сети)
  • Простота интерфейсов
  • Портативность компонентов
  • Лёгкость внесения изменений
  • Способность эволюционировать, приспосабливаясь к новым требованиям (на примере Всемирной паутины)

По-простому

Грубо говоря, REST это набор рекомендаций о том, как лучше сделать для получения преимуществ, описанных абзацем выше. Чем больше рекомендаций вы выполните, тем более REST получается приложение. А поскольку жизнь сложна, то это нормально, что REST ориентированными сервисы являются только отчасти. Использования REST как догмы ни к чему хорошему не приведёт. И REST никоим образом не заменяет собой RPC. Выбор решения зависит от ситуации и предъявляемых требований.

JSONAPI

Хотя REST и выглядит хорошо, он всё же слишком далек от конкретных реализаций и описывает только фундаментальные аспекты взаимодействия. Конкретные способы организации урлов, передаваемые данные, поведение в случае ошибок и многое другое, придётся продумывать самостоятельно.

Есть и другой путь. В 2013 году появился стандарт под названием jsonapi, в котором очень подробно описано как создавать REST-like сервисы. Для его реализации написано множество библиотек под все популярные языки программирования. Как минимум, я рекомендую с ним ознакомиться, а ещё лучше - взять на вооружение. Использование открытых стандартов в промышленном программировании делает нашу жизнь проще, бизнес богаче, а волосы шелковистее.

Дополнительные материалы