REST API часто проектируют «по учебнику»: CRUD, статусы, PATCH, 409. На бумаге всё аккуратно. В реальном проду

REST API часто проектируют «по учебнику»: CRUD, статусы, PATCH, 409. На бумаге всё аккуратно. В реальном продукте это почти всегда ломается о рост: новые источники трафика, частичные обновления, гонки запросов, ручные правки в админке.

Хороший API — не тот, где меньше спорных кейсов. Хороший API — тот, где ошибки предсказуемы для продукта и денег. Если клиент дважды отправил платеж, 409 важнее красоты схемы. Если статус заказа меняется асинхронно, PATCH без явной модели версий превращается в тихую потерю данных. Если в e-commerce нельзя восстановить историю изменения цены, вы потом не объясните расхождение в марже 📉

Контринтуитивно: «чистый» REST часто проигрывает прагматичному контракту. Сначала задайте не ресурсы, а бизнес-риски: где нужна идемпотентность, где допустима eventual consistency, где ошибка должна быть явной, а где — исправимой. API, который не защищает деньги, конверсию и учет, — это не архитектура, а красивая иллюзия.