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

Модель зрелости REST API Леонарда Ричардсона — концепция, которая оценивает уровень соответствия API принципам REST.

• Показывает эволюцию от простого RPC к полноценным REST API: чем выше уровень в модели, тем лучше выстроено API.

Применение

• Для анализа текущего состояния API.
• Для создания REST API, которые легко интегрируются и поддерживаются.
• Помогает сделать API более гибкими для бизнеса.

Напомним

URL (Uniform Resource Locator)

Указывает, где находится ресурс, и как к нему обратиться (например, протокол + адрес).

• Пример: https://example.com/page

URN (Uniform Resource Name)

Уникальное имя ресурса, независимое от его местоположения.

• Пример: urn:isbn:0451450523

URI (Uniform Resource Identifier)

Общий термин, включающий как URL, так и URN. Это идентификатор ресурса в сети.

• Пример: https://example.com или urn:isbn:0451450523

Уровни зрелости модели

0 Уровень: API как удалённый вызов процедур (RPC)

Иногда называется "болото оспы" (The Swamp of POX — Plain Old XML).

• API — точка входа, которая принимает параметры и возвращает результат (единственный endpoint).
• Использует HTTP только для взаимодействия компонентов распределённой системы.
• Например, XML-RPC и SOAP.
• Действия определяются через параметры запроса.

Пример: POST /api

{
  "action": "createUser",
  "data": {
    "username": "john_doe",
    "email": "john.doe@example.com",
    "password": "securepassword123",
    "profile": {
      "firstName": "John",
      "lastName": "Doe",
      "age": 30
    }
  }
}

1 Уровень: Разделение ресурсов через URL

• Несколько URI, один HTTP метод.
• Отдельные endpoints для каждого ресурса.
• Действия привязаны к URL.

Пример:

• GET /users — получение списка пользователей.
• POST /users — создание пользователя.

2 Уровень: HTTP-методы

• Несколько URI, каждый поддерживает разные HTTP методы.
• Используются методы HTTP, например, GET, POST, PUT, DELETE.
• Добавлены коды ответа HTTP (например, 200 OK, 404 Not Found).

Пример:

• GET /users/123 → возвращает пользователя.
• DELETE /users/123 → удаляет пользователя.

3 Уровень: HATEOAS для управления состоянием через ссылки

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

• Сервер предоставляет не только данные, но и гиперссылки. Они показывают клиенту действия, доступные с этим ресурсом.
• Ресурсы сами описывают свои возможности и взаимосвязи.

HATEOAS (Hypermedia as the Engine of Application State):

• Возвращает действия, которые могут быть выполнены с ресурсом, в виде URL.
• Дает возможность менять URI независимо от клиентов.

Пример:

{
  "tasks": [
    {
      "id": 1,
      "title": "Buy groceries",
      "status": "pending",
      "_links": {
        "self": "/tasks/1",
        "update": "/tasks/1/update",
        "delete": "/tasks/1/delete"
      }
    }
  ]
}

Зачем нужен HATEOAS

• Снижение связности: клиент строит взаимодействие на основе ссылок от сервера.
• Нет строгой зависимости от структуры URI, так как она указана в ответе.
• Клиенту не нужно знать заранее все URL, сервер подсказывает дальнейшие шаги.
• Изменения в API минимально влияют на клиентов, так как ссылки приходят динамически.

Применение HATEOAS

• Микросервисы и REST API: для динамической интеграции между сервисами.
• Бизнес-процессы: клиент "ведётся" по процессу через предоставленные сервером ссылки.
• Публичные API: улучшение документации через самоописание API.

Материалы

1. А ваша служба является RESTful? Все что необходимо/обязательно знать про веб службы и REST
2. Richardson Maturity Model – RESTful API (en)
3. REST и RPC: Введение в архитектуру HTTP API
4. Модель зрелости Ричардсона
5. Архитектура приложений и интеграции: гайд по основным понятиям простыми словами
6. REST API — Что такое HATEOAS?
7. REST API — Что такое HATEOAS?
8. Martin Fowler - Richardson Maturity Model
9. Кратко: Уровни развития API и модель Ричардсона
10. Андрей Бураков: REST, что же ты такое?

Видео

• Что такое HATEOAS за 4 минуты