rest api

REST API (Representational State Transfer Application Programming Interface) — архитектурный стиль взаимодействия между программными системами через протокол HTTP. Термин «REST» ввёл Рой Филдинг в своей докторской диссертации 2000 года, описав набор ограничений для создания масштабируемых распределённых систем. REST API сегодня является самым распространённым способом построения веб-сервисов, позволяя клиентам и серверам обмениваться данными независимо от технологий реализации.

Шесть принципов REST

Филдинг определил шесть архитектурных ограничений, соответствие которым делает API «RESTful»:

1. Клиент-сервер — разделение ответственности: клиент управляет UI и пользовательским состоянием, сервер — хранением данных и бизнес-логикой. Они взаимодействуют только через унифицированный интерфейс.
2. Stateless (без состояния) — каждый запрос содержит всю информацию, необходимую серверу для его обработки. Сервер не хранит сессионное состояние между запросами. Это ключевое ограничение для масштабируемости: любой экземпляр сервера может обработать любой запрос.
3. Кэшируемость — ответы должны явно помечаться как кэшируемые или нет (заголовки Cache-Control, ETag). Кэш на стороне клиента или CDN снижает нагрузку на сервер.
4. Единообразный интерфейс — стандартизированное взаимодействие через HTTP-методы, URI-идентификаторы ресурсов и согласованные форматы ответов.
5. Многоуровневая система — между клиентом и сервером могут быть промежуточные слои (прокси, балансировщики, CDN), прозрачные для клиента.
6. Код по требованию (необязательное) — сервер может передавать клиенту исполняемый код (JavaScript), расширяя его функциональность.

HTTP-методы и их семантика

REST использует стандартные HTTP-методы для операций над ресурсами:

• GET — получение ресурса или коллекции. Идемпотентный, безопасный. Не должен изменять состояние.
• POST — создание нового ресурса или выполнение действия. Не идемпотентный.
• PUT — полная замена ресурса. Идемпотентный: повторный запрос с теми же данными даёт тот же результат.
• PATCH — частичное обновление ресурса (только изменённые поля).
• DELETE — удаление ресурса. Идемпотентный.
• HEAD — как GET, но без тела ответа. Используется для проверки существования ресурса.
• OPTIONS — получение поддерживаемых методов. Используется при CORS preflight-запросах.

Дизайн URI: именование ресурсов

Хорошо спроектированный REST API использует существительные во множественном числе для ресурсов и иерархическую структуру URI:

• GET /users — список пользователей
• GET /users/{id} — конкретный пользователь
• POST /users — создание пользователя
• GET /users/{id}/orders — заказы конкретного пользователя
• PUT /users/{id}/orders/{orderId} — обновление заказа

Глаголы в URI — антипаттерн: не /getUser, а GET /users/{id}. Действия, не укладывающиеся в CRUD, выражают через субресурсы: POST /orders/{id}/cancel.

HTTP-статусы и обработка ошибок

Коды состояния HTTP передают семантику ответа:

• 2xx — успех: 200 OK, 201 Created, 204 No Content.
• 3xx — перенаправление: 301 Moved Permanently, 304 Not Modified.
• 4xx — ошибка клиента: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests.
• 5xx — ошибка сервера: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Тело ошибки должно содержать структурированную информацию (RFC 7807 Problem Details): тип ошибки, человекочитаемое сообщение, детали для отладки.

Форматы данных и заголовки

REST не обязывает использовать конкретный формат данных, но JSON стал стандартом де-факто. Заголовок Content-Type: application/json указывает формат тела запроса, Accept: application/json — предпочитаемый формат ответа. Для бинарных данных (файлы) используется multipart/form-data или прямой бинарный поток.

Версионирование REST API

Версионирование API необходимо для поддержки клиентов при внесении ломающих изменений. Три подхода: в пути URL (/v1/users, наиболее распространён), в заголовке (Accept: application/vnd.api+json;version=2) и в query-параметре (/users?version=2). Рекомендуется избегать ломающих изменений в существующих версиях и поддерживать предыдущую версию минимум 6–12 месяцев после выхода новой.

REST vs GraphQL vs gRPC

REST прост, широко поддерживается и хорошо кэшируется. GraphQL позволяет клиенту точно указать нужные поля, решая проблемы over-fetching и under-fetching, но сложнее в кэшировании. gRPC использует Protocol Buffers и HTTP/2, обеспечивая высокую производительность и строгую типизацию — идеален для внутренней межсервисной коммуникации. Выбор зависит от задачи: REST остаётся оптимальным для публичных API и простых CRUD-сервисов.