Контракт важнее количества endpoint
Когда один endpoint возвращает `error`, второй `message`, а третий HTTP 200 с `success:false`, frontend быстро наполняется исключениями. Единый формат ответа и ошибок делает систему дешевле в развитии.
Ошибки и pagination
Ошибка имеет machine-readable code, человеческое сообщение, field errors и request ID. Pagination выбирается осознанно: page удобен для таблиц, cursor — для больших динамических лент.
Idempotency
Повтор важного POST после сетевого сбоя не должен создавать второй заказ. Idempotency key связывает повторы с одной бизнес-операцией.
Versioning
Не каждое изменение требует `/v2`. Добавление необязательного поля обычно совместимо, а смена смысла и удаление — breaking change с периодом deprecation.
Вывод
API становится настоящим контрактом, когда мобильное приложение или интеграция могут развиваться без чтения внутреннего backend-кода.