исследуй
проектируй
Улучшай

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

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

Компоненты: клиент - отправитель запроса, сервер - приложение, владелец бизнес логики, обрабатывает запросы клиента и предоставляет ответы.
За счет сообщений типа "запрос" - "ответ" происходит взаимодействие между клиентом и сервером.

Больше деталей

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

• clients (клиенты)
• orders (заказы)
• items (товары - это и, собственно, билеты, сопутсвующие товары)
  Выше мы оговорились, что клиент и сервер общаются между друг другом посредством запросов и ответов.

Запрос

Запрос в общем случае состоит из:

• метода
• заголовка
• тела запроса
• URI

URI
Данные - это ресурсы, ресурсы - это основа взаимодействия.
В нашем сервисе ресурсами будут: clients, orders, items
URI описывает "адрес" ресурса, то есть путь, по которому к ресурсу следует обращаться.
К ресурсу должно быть возможно обратиться по уникальному пути или адресу.

Пример:
/clients — URI всех имеющихся клиентов;
/clients/71 — URI конкретного клиента, а именно клиента с ID=71;
/clients/14 — URI конкретного клиента, а именно клиента с ID=14.

/clients/71/orders — URI всех заказов клиента 71;
/clients/14/orders/1 — URI заказа 1 клиента 14.
/clients/71/orders/1/items — URI списка всех товаров в заказе 1 сделанного клиентом 71

При проектировании URI важно, чтобы они были читабельными, и глядя только на пути, можно было понять структуры и вложенность данных.

HTTP Метод
Метод - это действие над объектом.

• GET — получить информацию о конкретном объекте (через ID) либо о коллекции объектов;
• POST — создать объект;
• PUT — изменить объект (через ID);
• PATCH - изменить объект частично;
• DELETE — удалить объект (через ID).

Заголовок
Заголовки актуальны как для запросов, так и для ответов. Служат для передачи некоей служебной информации.
Больше информации про возможности заголовков - Википедия
Например, Accept:application/json - определяет, что клиент готов получить ответ в формате JSON

Тело запроса
Наличие или отсутствие тела в запросе зависит от метода и задачи.
GET & DELETE обычно не имеют тела. PUT & POST - да.
Чаще всего для передачи тела запроса используется JSON, реже - XML.
Допустим, нам необходимо создать клиента.
Мы отправим запрос типа POST и снабдим его телом:

{
  "name" : "Carlos",
  "surname": "Santana",
  "city" : "Rostov",
  "phone" : "+7 (332) 246-44-24"
}

Ответ

Включает в себя:

• заголовки
• код ответа
• тело ответа

HTTP коды ответов

• 201 Created;
• 401 Unauthorized;
• 507 Insufficient Storage.

Коды ответов подразделяются на несколько групп:

• 1ХХ — информационные;
• 2ХХ — информируют о случаях успешного принятия и обработки запроса клиента;
• 3ХХ — сообщают клиенту, что для успешного выполнения операции необходимо сделать другой запрос, как правило по другому URI;
• 4ХХ — ошибка клиента. Например, неправильно составленный запрос или же широко известный код 404 Not Found, которая может возникнуть, когда клиент запрашивает несуществующий ресурс;
• 5ХХ — ошибка сервера. Возвращается клиенту в случае неудачного выполнения операции по вине сервера.