Модель зрелости REST API Ричардсона

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

О чем она?

Модель зрелости REST API - концепция, которая оценивает API по нескольким параметрам и определяет, насколько этот интерфейс соответствует принципам REST. Т.е. является ли ваш сервис простым RPC или он уже эволюционировал в полноценный REST. Чем выше "уровень" вашего сервиса, тем лучше (по мнению Ричардсона) он спроектирован.

Уровни зрелости модели ➖ Уровень 0: API как RPC

Сервис имеет единственный URI, который использует единственный HTTP-метод (в основном POST). Т.е. API является точкой входа, которая принимает параметры и возвращает результат.По сути используется просто как обертка для вызова удаленных процедур (т.е. стандартный RPC), не используя RESTful принципы вообще.

Например: POST /api, в теле которого передается {"action": "deleteOrder", "data": {id: "123", ...}}. Как видим из примера, запрос обрабатывается не как операция с ресурсом (как мы привыкли), а как действие.

➖ Уровень 1: Resources

Сервис на этом уровне имеет несколько URI, каждый из которых использует только один HTTP метод. Разница между нулевым и первым уровне заключается в том, что на первом уровне сервис выставляет множество логических ресурсов, а на нулевом уровне сервис объединяет все взаимодействия через единственный (и намного более сложный) ресурс.

Кроме этого, в сервисах этого уровня имена операций, параметров и даже действий зашиты в сам URI.

Например: POST /deleteOrder. Или POST /getOrders.

➖ Уровень 2: HTTP-verbs

Сервис на этом уровне имеет много URI-адресуемых ресурсов и использует несколько HTTP-методов для каждого из них. Тут мы начинаем работать с концепцией CRUD, т.е. с управлением состояния ресурса (бизнес-сущности) через отдельные ручки.

То есть тут уже используется все многообразие методов (GET, POST, PUT, PATCH, DELETE), используем корректные коды ответа (200, 201, 404 и т.д.).

Например: GET /orders/123 DELETE /orders/123

➖ Уровень 3: HATEOAS

Самый высокий уровень зрелости в рамка этой модели.

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

По-другому это называется HATEOAS (Hypermedia as the Engine of Application State) — характеристика веб-сервиса возвращать действия, которые могут быть выполнены с ресурсом, в виде URL

Пример использования HATEOAS:

Есть сервис, который предоставляет возможность управлять заказами клиента. В ответ на запрос списка заказов сервер может вернуть ответ, в котором в том числе, будут гиперссылки: `{ "orders": [ { "id": 1, "goodsName": "Table", "status": "PAID", "_links": { "self": "/orders/1", "update": "/orders/1/update", "delete": "/orders/1/delete" } }, ... ➖self — ссылка на текущий ресурс; ➖update — ссылка на ресурс обновления заказа; ➖delete — ссылка на ресурс удаления заказа.

P.S. А у вас сервисы какого уровня? Оценивали ли вы их? Лично я на своей практики ни разу, кажется, на видел сервисов выше 2 уровня. Зачастую, это может быть излишне и в большинстве случаев просто нет такой необходимости. Но если кто-то сталкивался с таким - расскажите про свой опыт, пожалуйста.`