Как спроектировать REST API без ошибок: 3 задачи с разбором

Вот важная новость с фронта ИИ: sproshchaev 10 минут назад Как спроектировать REST API без ошибок: 3 задачи с разбором Средний 11 мин 182 Блог компании OTUS Карьера в IT-индустрии Анализ и проектирование систем * Java * Kotlin * Кейс Всем привет, меня зовут Сергей Прощаев. Я Tech Lead в FinTech и преподаватель в OTUS. Сегодня — не лекция, а диагностика.

За последние два года на собеседованиях 90% аналитиков уверенно рассуждают про REST, но путают PUT и PATCH, возвращают 200 при создании ресурса или забывают про версионирование. Поэтому три коротких кейса из практики — решите сами, а потом сверимся. Важно понимать: в API‑дизайне редко существует единственно правильный ответ.

Технические детали

Обычно это компромисс между HTTP‑семантикой, удобством клиентов, зрелостью платформы и стоимостью поддержки. Мои разборы — это аргументированная позиция, а не истина в последней инстанции. Диагностика: сможете ли вы спроектировать API, которое не сломается через полгода?

Метод и идемпотентность: простая операция, которая ломает productionУсловие. Вы проектируете API для сервиса управления подписками. Нужно реализовать операцию «отключить автопродление» для активной подписки пользователя.

Бэкенд‑разработчик говорит: «Сделаем POST /subscription/{id}/cancel-auto-renewal — это действие, оно не идемпотентно, каждый запрос отключает опцию». Продакт добавляет: «А если клиент по ошибке нажмёт кнопку дважды, ничего страшного — пусть просто вернёт успех». Остановитесь и выберите вариант (можно мысленно):Оставить POST /subscription/{id}/cancel-auto-renewal — клиент сам отвечает за дубли.

Отраслевые последствия

Использовать PUT /subscription/{id}/auto-renewal с телом {enabled: false} — при повторном вызове эффект тот же. Использовать DELETE /subscription/{id}/auto-renewal — удаляем свойство «автопродление». Сделать PATCH /subscription/{id} и передавать {"autoRenew": false}.

Я специально поставил этот кейс первым, потому что на реальных собеседованиях люди чаще всего выбирают вариант 1 или 4, но не могут объяснить, почему один лучше другого. Вариант 1 (POST с глаголом в URL) — это action‑oriented API‑подход, ближе к RPC‑стилю. Он широко используется в индустрии (Stripe, Kubernetes, AWS) и сам по себе не является ошибкой.

Но у него есть недостатки: сложнее обеспечивать единообразие семантики, идемпотентность и предсказуемость поведения API по мере роста системы. Вариант 2 (PUT на подресурс auto-renewal) — технически идемпотентен, PUT заменяет состояние ресурса целиком. Но здесь есть нюанс: подресурс auto-renewal — это логическое свойство основного ресурса subscription.

Этот прогресс даёт важные сигналы о будущем отрасли, и технологический мир внимательно наблюдает.