Модель зрелости Ричардсона
Продолжение статьи. Читать с начала.
Уровень 1 - ресурсы
Первым шагом к славе REST в модели Ричардсона является введение ресурсов. Теперь вместо того, чтобы делать наши запросы к единственной конечной точке сервиса, мы начинаем общаться с отдельными ресурсами.
Рис. Уровень 1 добавляет ресурсы
Поэтому для нашего первоначально запроса мы можем иметь ресурс для каждого доктора.
POST /doctors/mjones HTTP/1.1 [различные заголовки] <openSlotRequest date = "2010-01-04"/>
Ответ несет в основном ту же информацию, но теперь каждое время приема представляет собой ресурс, к которому можно адресоваться отдельно.
HTTP/1.1 200 OK [различные заголовки] <openSlotList> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/> <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/> </openSlotList>
Наличие конкретных ресурсов записи на прием означает отправку к определенному времени приема.
POST /slots/1234 HTTP/1.1 [различные заголовки] <appointmentRequest> <patient id = "jsmith"/> </appointmentRequest>
Если все прошло хорошо, я получаю такой ответ на предыдущий запрос.
HTTP/1.1 200 OK [различные заголовки] <appointment> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/> <patient id = "jsmith"/> </appointment>
Отличие теперь состоят в том, что если потребуется что-либо сделать относительно записи на прием, например, проверить наличие записи, сначала нужно иметь ресурс, URI которого может быть вида http://royalhope.nhs.uk/slots/1234/appointment, и обратиться к этому ресурсу.
Для тех, кто, как и я, живет в мире ООП, это подобно понятию идентичности объекта. Вместо вызова функции с передачей эй параметров, мы вызываем метод одного конкретного объекта, предоставляя параметры для другой информации.
Уровень 2 – HTTP-глаголы
Я использовал HTTP-глагол POST для всех моих взаимодействий на уровнях 0 и 1, однако некоторые люди используют вместо или наряду с этим GET. На данных уровнях в этом не было большой разницы, т.к. оба они используются как механизмы туннелирования, позволяя вам туннелировать ваши взаимодействия посредством НТТР. Уровень 2 уходит от этого, используя НТТР-глаголы максимально близко к тому, как они используются в самом НТТР.
Рис. Уровень 2 добавляет НТТР-глаголы
Что касается нашего списка времен записи на прием, то он означает, что мы хотим использовать GET.
GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Host: royalhope.nhs.uk
Ответ имеет тот же вид, что и при использовании POST,
HTTP/1.1 200 OK [различные заголовки] <openSlotList> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/> <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/> </openSlotList>
На уровне 2 использование GET для подобных запросов является критичным. НТТР определяет GET как безопасную операцию, которая не вносит каких-либо существенных изменений в состояние чего бы то ни было. Это позволяет нам безопасно вызывать GET неоднократно в любом порядке и получать при этом всякий раз одни и те же результаты. Как следствие, что важно, этот метод позволяет любому участнику в маршрутизации запросов использовать кеширование, которое является ключевым элементом в том, что делает веб таким, каким он является. НТТР включает различные средства поддержки кеширования, которые могут использоваться всеми участниками взаимодействия. Следуя правилам НТТР, мы можем получить выгоды из этой способности.
Чтобы записаться на прием, нам нужен НТТР-глагол, который меняет состояние – POST или PUT. Я буду использовать тот же POST, что и раньше.
POST /slots/1234 HTTP/1.1 [другие заголовки] <appointmentRequest> <patient id = "jsmith"/> </appointmentRequest>
Расхождений между использованием POST и PUT больше, чем я хотел бы здесь обсуждать, и, возможно, однажды я напишу отдельную статью по этому поводу. Однако сейчас я хочу указать на то, что некоторые люди некорректно проводят соответствие между POST/PUT и создать/обновить. Выбор между ними существенно отличается от этого представления.
Даже если я использую тот же самую отправку (post), что и на уровне 1, имеется еще одно существенное отличие в том, как отвечает удаленный сервис. Если все прошло хорошо, сервис отвечает с кодом 201, указывая на то, что в мире появился новый ресурс.
HTTP/1.1 201 Created Location: slots/1234/appointment [различные заголовки] <appointment> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/> <patient id = "jsmith"/> </appointment>
Ответ 201 включает атрибут расположения ресурса с помощью URI, который клиент может в дальнейшем использовать для запроса (GET) текущего состояния ресурса. Ответ здесь также включает представление этого ресурса, чтобы клиенту не пришлось делать лишний вызов.
Есть еще одно отличие для случая, когда что-то пошло не так, например, когда кто-то еще заказывает сеанс.
HTTP/1.1 409 Conflict [другие заголовки] <openSlotList> <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/> </openSlotList>
Важной частью такого ответа является использование кода ответа НТТР для указания того, что что-то пошло не так. В этом случае 409 представляется хорошим выбором, чтобы сообщить, что кто-то уже обновил ресурс несовместимым образом. Вместо использования кода возврата 200 с включением в ответ сообщения об ошибке, на уровне 2 мы явно используем некоторый вид ошибочного ответа, как в данном примере. Дело разработчика протокола решать какие коды использовать, но здесь не должно быть ответа 2хх, если возникла ошибка. Уровень 2 вводит использование НТТР глаголов и кодов ответа.
Здесь есть некое противоречие. Защитники REST говорят об использовании всех НТТР-глаголов. Они также обосновывают свой подход, говоря, что REST есть попытка научиться на успешном практическом использовании веба. Однако всемирная паутина не применяет массово PUT или DELETE на практике. Существуют веские причины для более широкого использования PUT или DELETE, однако доказательство существования сети не из их числа.
Ключевыми элементами, которые поддерживаются существованием сети, являются строгое разделение между безопасными (например, GET), и небезопасными операциями, наряду с использованием кодов состояния, чтобы сообщать о кодах ошибок, с которыми вы можете столкнуться.