Принципы проектирования API для долгоживущих систем

API — это контракты. После публикации их изменение ломает клиентов. Вот как проектировать API, которые переживут годы эволюции.

REST vs GraphQL vs tRPC

Выбор зависит от контекста: REST лучше для публичных API с неизвестными клиентами, GraphQL — для сложных вложенных данных и нескольких типов клиентов, tRPC — для TypeScript-монорепозиториев.

Стратегия версионирования

Никогда не версионируйте в URL (/api/v1/). Используйте заголовки или семантическое версионирование с окнами депрекации: объявляйте об устаревании за 6 месяцев.

Обработка ошибок

Единообразные ответы об ошибках так же важны, как успешные. Всегда включайте машиночитаемый код ошибки и человекочитаемое сообщение.

Документация, которая не врёт

Генерируйте документацию из кода, никогда не пишите её вручную. Написанная вручную документация всегда устаревает.