Версионирование API
Тема дорожной карты · Backend разработчик
Версионирование API — это практика управления несколькими сосуществующими версиями API для сохранения обратной совместимости при непрерывном выпуске новых функций и критических изменений. Три основные стратегии: версионирование через путь URL (например, /api/v2/users), версионирование через заголовок запроса с использованием кастомного Accept-Version или X-API-Version, и версионирование через медиа-тип с Accept: application/vnd.myapp.v2+json — у каждого из вариантов свои компромиссы в части кешируемости и обнаруживаемости. Политика версионирования REST API должна быть задокументирована в спецификации OpenAPI 3.x, чтобы потребители могли генерировать типизированные клиенты с помощью openapi-generator или swagger-codegen. При создании микросервисов с gRPC встроенная в Protobuf схема нумерации полей обеспечивает версионирование API на уровне схемы, позволяя добавлять новые поля без нарушения совместимости с существующими потребителями. Периоды долгосрочной поддержки (LTS) и чёткие уведомления об устаревании через заголовки ответа (Sunset, Deprecation) — обязательные операционные практики, предотвращающие внезапный сбой у потребителей API в продакшене.
Как это работает
Версионирование API имеет три доминирующих стиля: REST (resource-oriented, использует HTTP-семантику, легко кешируется), GraphQL (клиент выбирает форму, один endpoint, хорошо для разных клиентов), gRPC/RPC (вызов процедур, строгая схема, низкий overhead). Хороший API предсказуем: консистентные имена, версионирован (/v1/users), пагинация для коллекций (курсор лучше offset), фильтруем, идемпотентен где безопасно, задокументирован (OpenAPI для REST, .proto для gRPC, schema для GraphQL).
Когда применять
REST — для публичных API, которые потребляет много третьих сторон: lowest common denominator. GraphQL — когда один backend обслуживает много форм клиента (web + iOS + Android с разными нуждами) и хотите избежать bespoke endpoint на клиента. gRPC — для internal service-to-service, где важны latency + типизированные контракты. Микс ок: публичный REST + internal gRPC — частый кейс.
Типичные ошибки
Ловушки Версионирование API: нет версионирования ("добавим версию потом" — к тому моменту breaking change для всех); глубоко вложенные ресурсы (/users/123/orders/456/items/789 — плоский лучше); chatty API (клиент делает 10 вызовов на одну страницу — батчите или expand related); утечка внутренних ID (auto-increment integer выдаёт объём — UUID лучше); непоследовательный формат ошибок. Пишите доки API так, будто их прочитает незнакомец.