REST API и Richardson Maturity

REST API (Representational State Transfer Application Programming Interface) — архитектурный стиль проектирования сетевых сервисов, использующий стандартные HTTP-методы, stateless семантику запрос/ответ и URL-адреса, ориентированные на ресурсы, для создания совместимых, масштабируемых бэкенд-интерфейсов. REST API отображают CRUD-операции на HTTP-глаголы — GET для получения, POST для создания, PUT/PATCH для обновления, DELETE для удаления — и передают намерение через коды состояния HTTP: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Unprocessable Entity и 429 Too Many Requests. Поскольку REST API stateless, каждый запрос должен нести полный контекст аутентификации — обычно bearer-токен JWT или access-токен OAuth 2.0 в заголовке Authorization, — обеспечивая прозрачную балансировку нагрузки и горизонтальное масштабирование без sticky sessions. Контракты REST API задаются через OpenAPI / Swagger, что обеспечивает автоматическую генерацию документации, mock-серверы для фронтенд-разработки и контрактное тестирование в CI/CD-пайплайнах для выявления нарушений обратной совместимости до деплоя. Хотя REST API доминирует в веб-сервисах, команды, строящие низкозадержанную межсервисную коммуникацию в микросервисах, могут дополнять его gRPC (бинарный протокол поверх HTTP/2) или событийным обменом через Apache Kafka или RabbitMQ в зависимости от требований к связанности и пропускной способности.

Как это работает

REST API и Richardson Maturity имеет три доминирующих стиля: REST (resource-oriented, использует HTTP-семантику, легко кешируется), GraphQL (клиент выбирает форму, один endpoint, хорошо для разных клиентов), gRPC/RPC (вызов процедур, строгая схема, низкий overhead). Хороший API предсказуем: консистентные имена, версионирован (/v1/users), пагинация для коллекций (курсор лучше offset), фильтруем, идемпотентен где безопасно, задокументирован (OpenAPI для REST, .proto для gRPC, schema для GraphQL).

Когда применять

REST — для публичных API, которые потребляет много третьих сторон: lowest common denominator. GraphQL — когда один backend обслуживает много форм клиента (web + iOS + Android с разными нуждами) и хотите избежать bespoke endpoint на клиента. gRPC — для internal service-to-service, где важны latency + типизированные контракты. Микс ок: публичный REST + internal gRPC — частый кейс.

Типичные ошибки

Ловушки REST API и Richardson Maturity: нет версионирования ("добавим версию потом" — к тому моменту breaking change для всех); глубоко вложенные ресурсы (/users/123/orders/456/items/789 — плоский лучше); chatty API (клиент делает 10 вызовов на одну страницу — батчите или expand related); утечка внутренних ID (auto-increment integer выдаёт объём — UUID лучше); непоследовательный формат ошибок. Пишите доки API так, будто их прочитает незнакомец.

Связанные понятия

• API дизайн
• GraphQL
• gRPC
• OpenAPI и Swagger