Сейчас (и уже достаточно давно) аналитики при разработке решения по интеграции систем (или элементов одной системы) применяют интеграцию на основе API, в том числе руководствуясь принципами RESTful API. Пришло время поговорить о том, можно ли каким-то образом оценить соответствие реализации API данным принципам, есть ли какие показатели для такой оценки?
Самым распространенным инструментом для оценки зрелости API является модель зрелости Ричардсона (Richardson Maturity Model, RMM), которая классифицирует API на предмет соответствия принципам RESTful и позволяет оценить "эволюцию" вашего API.
Данная модель классифицирует API по 4-ём уровням:
1. Уровень 0 («сырые данные») - API представлены как обычные сервисы с использованием протокола HTTP (и работающих поверх него, пример: SOAP). Используется один URI для всего API и один HTTP-метод (обычно POST). Соответственно поддержка CRUD реализуется также через один метод POST;
Пример:
POST /api/reservation HTTP/1.1 - все операции с резервирование (товары, недвижимость, время приема), включая создание резерва / отмену / обновление / просмотр (CRUD)
2. Уровень 1 («ресурсы») - API начинает использовать понятие ресурсов (например, URL представляет ресурсы), но не соответствует принципам REST. В этом случае используются отдельные URI для отдельных ресурсов. Используется один метод POST;
Пример:
- POST /api/goods HTTP/1.1 - все операции с товарами: создание / отмена / обновление / просмотр (CRUD)
- POST /api/rooms HTTP/1.1 - все операции с недвижимость: создание / отмена / обновление / просмотр (CRUD)
- POST /api/cars HTTP/1.1 - все операции с автомобилями, создание резерва / отмену / обновление / просмотр (CRUD)
3. Уровень 2 ("HTTP+REST") - API становится более REST-подобным, используя стандарты HTTP (методы и статусы) и адресацию ресурсов;
Пример:
- GET /api/goods HTTP/1.1 - получение списка товаров
- POST /api/goods HTTP/1.1 - создание товара
- PUT /api/goods HTTP/1.1 - обновление товара
Коды ответов: 200 (успешно отработан), 201 (успешно создан), 404 (отсутствует запрошенный ресурс)
4. Уровень 3 ("HATEOAS") - API предоставляет гипермедиа-управляемые возможности, позволяя клиентам исследовать API и взаимодействовать с ним динамически. В ответе от сервера возвращаются ссылки на связанные ресурсы и действия, которые клиенты могут выполнять дальше (HATEOAS "гипермедиа");
Пример:
Запрос - GET /api/goods HTTP/1.1 - получение списка товаров
Ответ -
{"id": 12,
"amount": 3,
"color": "red",
"weight": 12.5,
"producer": 34;
"links": {"reservation": "/api/reservation/12",
"producer": "/api/producer/34"}
}
Больше другой полезной информации в ТГ канале: https://t.me/all_for_analyse
Важно заметить, что данная модель учитывает только следующие факторы:
- URI - идентификация ресурса;
- HTTP-методы - методы, используемые при обращении к объектам;
- HATEOAS - подход, согласно которому сервер возвращает не только запрошенный ресурс, но и его связи с другими ресурсами и действия, которые можно с ним совершить.
Что дает понимание соответствие API соответствующему уровня модели Ричардсона? Справедливый вопрос и ответ следующий: модель помогает определить степень соответствия принципам RESTful, а значит степень простоты, гибкости и масштабируемости API решения.
На практике, делая вывод о степени зрелости анализируемого API, нужно понимать, что не для каждого API требуется достигать 3-го уровня, все определяется индивидуально, в том числе и из-за специфики потребителей сервиса.
Другие полезные материала на канале: