C# Academy · Урок

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

Версионируйте API с помощью URL, заголовков и строки запроса.

«Стратегии версионирования API» — бесплатный урок C# Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения C# Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс C# Academy содержит 4 уроков всего.

Зачем версионировать API

Как только клиенты начинают зависеть от вашего API, вы больше не можете нарушать его контракт. Версионирование позволяет выпускать несовместимые изменения в новой версии, пока старые клиенты продолжают работать со старой.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Версионирование в пути URL

Самая заметная стратегия помещает версию в путь. Это однозначно и упрощает маршрутизацию, просмотр и кэширование.

GET /api/v1/products
GET /api/v2/products

Версионирование в строке запроса

Версия передаётся как параметр запроса. URL остаются неизменными, а при отсутствии параметра можно выбрать последнюю или фиксированную версию по умолчанию.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Версионирование в заголовке

Пользовательский заголовок запроса содержит версию, сохраняя чистоту URL. Недостаток в том, что версия не видна в адресной строке браузера и её сложнее проверять вручную.

GET /api/products
X-Api-Version: 2.0

Версионирование по типу содержимого

Также называется согласованием содержимого. Версия встраивается в тип содержимого заголовка Accept. Это наиболее соответствующий REST, но наименее очевидный для обнаружения вариант.

GET /api/products
Accept: application/json;v=2.0

Сравнение стратегий

Каждая стратегия представляет компромисс между обнаруживаемостью и чистотой URL:

Путь URL: проще всего обнаружить, но URL становятся перегруженными.
Строка запроса: стабильные URL и удобные значения по умолчанию.
Заголовок: чистые URL, но версия скрыта от браузеров.
Тип содержимого: наиболее чистый REST-подход, но самый сложный в использовании.

// Many teams pick URL path for public APIs

Семантическое версионирование API

Версии API обычно ограничиваются только мажорными версиями (v1, v2). Минорные версии следует оставлять для добавочных обратно совместимых изменений, которые старые клиенты могут игнорировать.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Устаревание версии

Никогда не удаляйте старую версию внезапно. Пометьте её как устаревшую, объявите дату прекращения поддержки и сообщите об этом клиентам через заголовки.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Версия по умолчанию

Определите, что происходит, когда клиент не указывает версию. Распространённые варианты: использовать последнюю версию, использовать v1 или отклонить запрос. Явное решение позволяет избежать неожиданностей.

// Strategy: unversioned request -> treat as v1.0

Версионирование нужных частей

Версионируйте контракт (маршруты, формы запросов и ответов), а не внутренние детали реализации. Конечная точка v2 может использовать большую часть бизнес-логики v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Сочетание стратегий

Библиотека версионирования ASP.NET Core может одновременно считывать версию из нескольких источников, позволяя клиентам выбирать наиболее удобный вариант. Настроим это далее.

// Accept version from URL OR header OR query

Быстрая проверка

Проверьте, насколько хорошо вы понимаете стратегии версионирования.

Итоги

Вы рассмотрели стратегии версионирования API:

путь URL, строку запроса, заголовок и тип содержимого.
Каждая из них представляет компромисс между обнаруживаемостью и чистотой URL.
Версионируйте контракт, корректно объявляйте устаревание и определяйте версию по умолчанию.

Далее: настройка Asp.Versioning в ASP.NET Core.

Часто задаваемые вопросы

Урок «Стратегии версионирования API» бесплатный?

Да — полный текст урока «Стратегии версионирования API» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс C# Academy, подпишись на CoddyKit PRO. Курс C# Academy содержит 4 уроков всего.

Чему я научусь в уроке «Стратегии версионирования API»?

Версионируйте API с помощью URL, заголовков и строки запроса. Ты практикуешь C# Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать C# Academy?

Предыдущий опыт не требуется. C# Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Стратегии версионирования API»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке C# Academy?

Да. Каждый урок C# Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к C# Academy