Как отличить проектирование API «по учебнику» от рабочей схемы? По тому, как человек отвечает на 3 базовых воп

Как отличить проектирование API «по учебнику» от рабочей схемы? По тому, как человек отвечает на 3 базовых вопроса: где граница ресурса, что делать с частичным обновлением и как возвращать ошибки так, чтобы их можно было автоматизировать.

Если переносить это на Ozon-логику, то REST — это не «красивый интерфейс», а контракт между системами. Ошибка на уровне контракта потом бьёт по складу, фидам и синхронизации карточек: статус обновился не там, товар ушёл в неактуальную воронку, а обработка дублей превращается в ручной разбор.

3 маркера зрелого API-дизайна:
1) ресурс описан без лишней магии — понятно, что является сущностью, а что атрибутом;
2) методы не смешивают полное и частичное обновление;
3) коды ошибок помогают системе принять решение, а не просто «что-то пошло не так» ⚙️

Практический вывод: хороший API проектируют не вокруг удобства разработчика, а вокруг стабильности процесса. Там, где есть спор про PATCH или 409, почти всегда есть спор и про цену ошибки в данных.