REST Best Practices — Проектирование API

Лучшие практики REST

REST (Representational State Transfer) — это архитектурный стиль для создания веб-сервисов, который использует стандартные возможности протокола HTTP для взаимодействия с ресурсами.

#Основные принципы

Ресурсы: Все данные и функциональность представлены как ресурсы, доступные по уникальным URI (например, /users, /orders/123).
HTTP методы: Для манипуляции с ресурсами используются стандартные HTTP-глаголы:
- GET — получение ресурса (безопасный и идемпотентный).
- POST — создание нового ресурса или выполнение действия.
- PUT — полная замена ресурса (идемпотентный).
- PATCH — частичное обновление ресурса.
- DELETE — удаление ресурса (идемпотентный).
Статусные коды: Использование семантических кодов состояния HTTP для указания результата операции (200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error и т.д.).

#Модель зрелости Ричардсона (Richardson Maturity Model)

Эта модель описывает четыре уровня зрелости RESTful API:

Level 0: Один URI, все операции через POST. Это похоже на SOAP, где HTTP используется только как транспорт.
Level 1: Введение ресурсов. Каждый ресурс имеет свой URI (например, /users, /orders).
Level 2: Использование HTTP-методов и статусных кодов. Это самый распространенный уровень. API становится по-настоящему RESTful.
Level 3: Добавление HATEOAS (Hypermedia As The Engine Of Application State). Ответы содержат ссылки на связанные ресурсы и доступные действия, что позволяет клиенту динамически обнаруживать API.

#HATEOAS

HATEOAS — это философия, при которой API не просто возвращает данные, но и предоставляет клиенту информацию о том, что можно сделать дальше. Например, ответ на запрос GET /orders/123 может содержать не только данные заказа, но и ссылки на действия, которые можно с ним совершить: отменить (/orders/123/cancel) или получить счет (/orders/123/invoice). Это повышает гибкость и упрощает поддержку API, так как URL-адреса могут меняться без необходимости обновления клиентского кода.

Пример ответа с HATEOAS:

{
  "id": 123,
  "status": "pending",
  "amount": 99.99,
  "currency": "USD",
  "_links": {
    "self": {
      "href": "/orders/123"
    },
    "cancel": {
      "href": "/orders/123/cancel",
      "method": "POST"
    },
    "invoice": {
      "href": "/orders/123/invoice",
      "method": "GET"
    },
    "payment": {
      "href": "/orders/123/payment",
      "method": "POST"
    }
  }
}

Клиент использует ссылки из _links, а не конструирует URL вручную. Это делает клиент более слабосвязанным с API.