Учебник по RESTful API

В современной веб-разработке RESTful API стали стандартным способом взаимодействия приложений друг с другом.

REST (Representational State Transfer) — это стиль программной архитектуры, предложенный доктором Роем Филдингом в 2000 году.

REST определяет набор ограничений и принципов для создания масштабируемых, слабо связанных веб-сервисов.

RESTful API — это API, спроектированный в соответствии с архитектурным стилем REST. Он использует особенности протокола HTTP для поиска ресурсов по URL-адресам и применяет методы HTTP (GET, POST и т. д.) для описания операций, обеспечивая взаимодействие между клиентом и сервером.


Кому следует читать это руководство?

Независимо от того, являетесь ли вы фронтенд-разработчиком, которому нужно взаимодействовать с серверными API, или бэкенд-разработчиком, которому нужно проектировать интерфейсы API, освоение RESTful API — это необходимый навык.


Особенности RESTful API?

Ключевые особенности:

  • Без сохранения состояния: Каждый запрос содержит всю информацию, необходимую для обработки
  • Унифицированный интерфейс: Использует стандартные методы HTTP для операций
  • Ориентированность на ресурсы: Всё представляется в виде ресурсов
  • Кэшируемость: Ответы должны явно указывать, подлежат ли они кэшированию

Основные принципы RESTful API

1. Ресурсы и URI

В REST всё представляется в виде ресурса, и каждый ресурс имеет уникальный идентификатор (URI).

Рекомендации по проектированию URI:

  • Используйте существительные, а не глаголы, для представления ресурсов
  • Используйте формы множественного числа для коллекций
  • Используйте строчные буквы и дефисы (-)
  • Избегайте расширений файлов

Пример:

/users          # 用户集合
/users/123      # ID为123的用户
/users/123/orders  # 用户123的订单集合

2. Использование методов HTTP

RESTful API в полной мере используют семантику методов HTTP:

HTTP-метод Описание Идемпотентность Безопасность
GET Получение ресурса Да Да
POST Создание ресурса нет нет
PUT Полное обновление ресурса Да нет
PATCH Частичное обновление ресурса нет нет
DELETE Удаление ресурса Да нет

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

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

4. Формы представления

Ресурсы могут иметь несколько форм представления (например, JSON, XML), а клиент указывает желаемый формат с помощью заголовка Accept.

Другие расширения