Junior Level

RESTful дизайн — это правила создания API, которые следуют принципам REST.

Основные правила:

1. Используйте существительные для ресурсов:
   • ✅ GET /users — получить пользователей
   • ❌ GET /getUsers — глаголы не нужны
2. Используйте правильные HTTP методы:
   • GET — чтение
   • POST — создание
   • PUT — полное обновление
   • PATCH — частичное обновление
   • DELETE — удаление
3. Используйте множественное число:
   • Рекомендуется множественное число — это наиболее распространённая конвенция.
   • Но единственное число тоже допустимо, если команда договорилась.
   • ✅ /users, /orders, /products
   • ❌ /user, /order, /product
4. Возвращайте правильные статус-коды:
   • 200 — успех
   • 201 — создано
   • 400 — ошибка клиента
   • 404 — не найдено
   • 500 — ошибка сервера

Пример хорошего RESTful API:

GET    /users          — список пользователей
GET    /users/1        — пользователь с ID 1
POST   /users          — создать пользователя
PUT    /users/1        — обновить пользователя целиком
PATCH  /users/1        — частично обновить пользователя
DELETE /users/1        — удалить пользователя

---

Middle Level

Richardson Maturity Model

• Level 0 (The Swamp of POX): HTTP как транспорт (RPC через HTTP)
• Level 1 (Resources): Использование ресурсов (отдельные URI)
• Level 2 (HTTP Verbs & Statuses): HTTP методы и статус-коды. Это “золотой стандарт” индустрии
• Level 3 (HATEOAS): Гипермедиа. Самый дорогой уровень — оверхед на построение графа ссылок и увеличение JSON на 30-50%

Design-First vs Code-First

1. Design-First (OpenAPI/Swagger YAML): Сначала контракт, затем генерируется код
   • Плюс: Параллельная разработка фронтенда и бэкенда. Гарантия соответствия документации
   • Минус: Сложность поддержки YAML при частых изменениях
2. Code-First (SpringDoc/Swagger Annotations): Сначала код, документация генерируется из аннотаций
   • Плюс: Быстрая итерация
   • Минус: Документация часто “лагает” относительно кода

Производительность

• Idempotency в дизайне: Проектируйте API так, чтобы PUT и DELETE были безопасными для повторов. Это позволяет использовать агрессивные политики повторов на уровне Service Mesh (Istio)
• Payload Optimization: В Highload-системах вместо JSON используют REST-over-Protobuf или MessagePack
• Negative Caching: Negative Caching — кеширование ошибочных ответов. Если злоумышленник сканирует API несуществующими запросами, CDN отдаст кешированный 404 вместо нагрузки на бэкенд. 1 секунда — компромисс: защита от brute-force без риска, что легитимный клиент долго не увидит появившийся ресурс. Настройте CDN так, чтобы ответы 404 и 403 кешировались на короткое время (1 сек).

N+1 Problem в REST

В отличие от GraphQL, REST страдает от избыточных запросов.

• Решение: Параметр embed или include (/orders?include=items)

HTTP Method Tunneling

Если клиент не поддерживает PATCH, используйте POST с заголовком X-HTTP-Method-Override: PATCH.

---

Senior Level

Когда RESTful дизайн избыточен

1. Внутренние микросервисы — лучше gRPC/Thrift
2. Real-time streaming — WebSocket/gRPC
3. Simple RPC-вызовы без CRUD-семантики

DispatcherServlet и HandlerMapping

В Spring MVC за реализацию RESTful дизайна отвечает DispatcherServlet, который использует HandlerMapping для сопоставления комбинации HTTP Method + URI с конкретным методом контроллера.

Уровни зрелости и их цена

• Level 2: Здесь важно не только использовать POST, но и возвращать 201 Created с заголовком Location
• Level 3: Основная сложность — оверхед на построение графа ссылок и увеличение размера JSON

Диагностика и Мониторинг

• Correlation ID: Рекомендуется включать X-Request-ID (или X-Correlation-ID) в каждый ответ. Этот ID передаётся через все микросервисы в цепочке вызовов, позволяя собрать все логи одного запроса в ELK.
• Problem Details (RFC 9457): Spring Boot 3+ поддерживает через ProblemDetail. Делает ошибки машиночитаемыми
• Latency Monitoring: Отслеживайте гистограммы задержек (P99) не по эндпоинтам, а в разрезе методов (GET vs POST), так как их профиль нагрузки принципиально разный

Edge Cases

• Trailing Slash: /users/ и /users — два разных ресурса. Настройте StrictTrailingSlashPatternMatch в Spring
• API Discovery: Хорошо спроектированное API позволяет вызвать OPTIONS /users и получить список доступных методов

---

🎯 Шпаргалка для интервью

Обязательно знать:

• RESTful дизайн = существительные в URI + правильные HTTP методы + множественное число + статус-коды
• Richardson Maturity Model: Level 2 (HTTP Verbs + Status Codes) — золотой стандарт индустрии
• Design-First (OpenAPI/Swagger) vs Code-First (SpringDoc) — Design-First гарантирует параллельную разработку
• HATEOAS (Level 3) — самый дорогой уровень, оверхед 30-50% на JSON, не нужен для внутренних микросервисов
• N+1 Problem в REST решается через embed/include параметры (/orders?include=items)
• Negative Caching — кеширование 404/403 ответов для защиты от brute-force сканирования
• Для внутренних микросервисов лучше gRPC, для real-time — WebSockets

Частые уточняющие вопросы:

• Почему множественное число в URI? — /users представляет коллекцию, /users/1 — элемент коллекции
• Когда Design-First лучше Code-First? — Когда фронтенд и бэкенд разрабатываются параллельно
• Что такое API Discovery? — Вызов OPTIONS /resource возвращает список доступных методов
• Почему HATEOAS редко используется? — Оверхед на генерацию ссылок, увеличение JSON на 30-50%, не нужен при одной команде

Красные флаги (НЕ говорить):

• «Глаголы в URL — это нормально для REST» — URI должен быть существительным, действие = HTTP метод
• «HATEOAS обязателен в каждом проекте» — для внутренних API и mobile приложений избыточен
• «REST подходит для всего» — для streaming и RPC лучше gRPC/WebSockets
• «Code-First всегда лучше» — документация часто отстаёт от кода, Design-First даёт контракт

Связанные темы:

• [[Что такое REST]]
• [[Как правильно именовать REST endpoints]]
• [[Стоит ли использовать глаголы в URL]]
• [[Что такое HATEOAS]]
• [[Какие HTTP статус коды вы знаете]]