Чи безкоштовна ця стаття?

Так. Усі статті на CoderSlingo, включно з цією, доступні безкоштовно без реєстрації.

Коли опубліковано цю статтю?

Цю статтю опубліковано у 2026 році.

API Versioning Vocabulary: URI vs Header vs Content-Type Versioning (англійською)

Q: Про що ця стаття "API Versioning Vocabulary: URI vs Header vs Content-Type Versioning (англійською)"?

Майстер лексики версії API — шлях URL, заголовок і стратегії типів вмісту, семантичні версії, застаріння, заголовки затемнення, розрив змін і запис changelog.

API - це контракти між командами, продуктами і компаніями. Коли ці контракти змінюються, вам потрібна чітка стратегія версії і мова для повідомлення про зміни кожному користувачеві. Незалежно від того, чи ви розробляєте публічний API, пишете повідомлення про заборону використання, або переглядаєте підручник з переходу на нову версію, словник, який ви знайдете у цій статті, допоможе вам мати чітке і професійне мовлення.

Версійні стратегії

Версія URL шляху

** Версії шляху URL ** вбудовує номер версії безпосередньо в URI: /api/v1/users, /api/v2/users. Це найпомітніша і широко розуміна стратегія.

«Ми використовуємо версію URL шляху — v1 залишається живим протягом 18 місяців після запуску v2, тому існуючі клієнти мають час мігрувати»

Переваги: просте читання, просте маршрутизування, працює з будь- яким HTTP- клієнтом. Недолік: зміна версії впливає на адресу URL кожної кінцевої точки, навіть тих, які не змінилися.

Версії параметрів запиту

** Запит параметра версії ** передає версію як рядок запиту: /api/users?version=2. Менш поширений в REST API, але зустрічається в деяких застарілих системах.

«Версування параметрів запитів робить простим тестування різних версій у браузері, але це занадто складно для клієнтських бібліотек.»

Версія заголовка

** Версії заголовків ** передають запитану версію у нетиповому заголовку HTTP- запиту, наприклад, API-Version: 2. Адреса URL залишається чистою.

«Ми перейшли на версію заголовка, тому URL залишається стабільним і переговори про версію відбуваються на рівні протоколу.»

Перевірка версії контенту

** Переговори щодо вмісту ** використовують заголовок Accept з типом носія виробника: Accept: application/vnd.myapp.v2+json. Це найбільш RESTful підхід в теорії, але найскладніший для реалізації і зневадження.

«Версування переговорів контенту є елегантним, але важче перевірити вручну — виклики curl швидко стають розмовними»

Семантичний версування для API

Семантична версія (SemVer)

** Семантичний контроль версій ** використовує схему MAJOR.MINOR.PATCH. Для API:

MAJOR — зміна, що вимагає від споживачів оновлення
MINOR — нова, зворотньо сумісна функція
PATCH — зворотньо сумісний виправлення помилок

«Це невелике видання — ми додаємо нове необмежене поле. Існуючим клієнтам не потрібно нічого змінювати»

Зміни змінюються

** Зміна, що порушує правила ** — це будь- яка модифікація, яка призводить до невдачі існуючих, правильно написаних клієнтів. Приклади: вилучення поля, перейменування поля, зміна типу поля, вимога нового обов’ язкового параметра.

«Видалення поля username є руйнівною зміною. Нам потрібно зберегти його в відповіді — позначити його як застарілий спочатку, видалити його в v3.”

Необхідні зміни

** Непереривна зміна ** (також відома як * зворотньо сумісна зміна *) не впливає на існуючі клієнти. Приклади: додавання нового необов’ язкового поля, додавання нової кінцевої точки, додавання нового необов’ язкового параметра запиту.

“Додати поле avatarUrl не є нерозривним. Існуючі клієнти просто ігноруватимуть це»

Зворотна сумісність

** Обратна сумісність ** (або ** обертова сумісність **) означає, що старі клієнти продовжуватимуть працювати правильно після зміни. Це є основною метою управління життєвим циклом API.

«Ми гарантуємо зворотну сумісність в рамках головної версії. Якщо ми зробимо зміну, ми зупинимо головну версію»

Життєвий цикл

Стадії життєвого циклу

Типовий інтерфейс API проходить через такі етапи:

Design — визначає контракт: кінцеві точки, форми запитів/відповідей, автентифікацію
** Збудувати ** — реалізація API
** Опублікувати ** — зробити його доступним для користувачів
** Застаріла ** — сигналізує про те, що цю версію або кінцеву точку буде вилучено з використання
Відхід - вимкнути

«Кінечна точка автентифікації v1 знаходиться на стадії застарілого — вона все ще працює, але ми кажемо споживачам перейти до v2 зараз»

Повідомлення про застарівання

** Повідомлення про виключення ** — це офіційне повідомлення про те, що функціональність, кінцева точка або версія буде вилучено у майбутньому. Це дає споживачам час для міграції.

“Ми відправили повідомлення про застарівання шість місяців тому. Дата заходу сонця наступного кварталу — в цей момент v1 повертає 410 Gone.”

Заголовок заходу сонця

Заголовок ** Sunset HTTP ** повідомляє клієнтам дату, коли версія кінцевої точки або API буде припинена. Він стандартизований в RFC 8594.

Додати заголовок Sunset: Sat, 01 Jan 2027 00:00:00 GMT до всіх v1 відповідей, щоб клієнти могли планувати свою міграцію

Documentation

Changelog

** API changelog ** документує кожну зміну API в зворотному хронологічному порядку. Це перше місце, куди розробник дивиться, коли щось ламається після оновлення.

Хороші записи журналу змін є конкретними і дійсними. Використовувати цей формат:

## v2.3.0 — 2026-06-04
### Added
- `GET /users/{id}/preferences` — returns user preference settings.
### Changed
- `POST /orders` now accepts an optional `couponCode` field.
### Deprecated
- `GET /users/{id}/settings` — use `/preferences` instead. Removal in v3.0.
### Breaking changes (v3.0 preview)
- `GET /users` will no longer include the `legacyId` field.

Завжди відокремлюйте «Додано», «Змінено», «Застаріло» і «Злам» секції в своєму changelog — споживачі сканують для розбиття змін спочатку

Руководство по миграции

** Посібник з міграції ** веде користувачів API через конкретні кроки, необхідні для оновлення з однієї версії на іншу. Він перетворює зміни в дії на дії.

«Ми опублікували посібник з міграції v1-до-v2 з прикладами коду до / після кожної зміни. Рівень прийняття удвічі в порівнянні з попередніми міграціями»

Фрази версії Common API

Phrase	Meaning
”This is a breaking change”	Existing clients will need to update
”We’re deprecating this endpoint”	It still works but will be removed; migrate now
”What’s your sunset timeline?”	When will you shut down the old version?
”We maintain two major versions”	Current and previous are both live
”Add this to the changelog”	Document the change for consumers
”Is this backwards-compatible?”	Will existing clients still work without changes?
”Version negotiation”	How the client and server agree on which version to use

Навигація по змінах: практичний підхід до версії API

Погляньмо правді в очі — API розвиваються. Вони необхідно еволюціонувати. Але керувати цією еволюцією, не перериваючи клієнтів, це делікатесне мистецтво. Словник, що оточує версії API, може бути заплутаним, особливо якщо ви розглядаєте різні стратегії для сигналізації змін. Ця стаття має на меті пояснити ці терміни і те, як вони поєднуються, зосереджуючись на практичному застосуванні, а не на теоретичних визначеннях. Ми розглянемо, як ці концепції працюють в реальних сценаріях - від перегляду коду до розмов Slack про майбутні оновлення.

Одним з найбільших викликів є ефективне обмінювання рішеннями щодо версії. Уявіть, що розробник намагається внести зміни з новим заголовком Content-Type: application/v2, супроводжуваним повідомленням « Використання останнього API! » Це місце, де точна термінологія стає вирішальною. Стратегия версії * URI *, наприклад, залежить від модифікації шляху URL - /api/v2/users - щоб вказувати на іншу версію. Цей метод часто використовується для простих змін, оскільки його відносно легко зрозуміти і реалізувати. Однак, покладаючись виключно на URI може призвести до плутанини, якщо декілька версій розгортаються одночасно. І навпаки, використання версії * заголовок * - як приклад Content-Type вище - дозволяє більшу гнучкість, але вимагає від клієнтів активно стежити за заголовками для оновлення. * Content-Type * версія є менш поширеною зараз через розвиток стандартів і потенційну неоднозначність навколо переговорів про зміст.

Ключова концепція, пов’язана з усіма цими стратегіями, є * семантичне версування * (SemVer), яке забезпечує структурований підхід до комунікації природи змін. Зміна v2 може означати зворотну сумісність, тоді як v3 може вказувати на зміни, що вимагають оновлення клієнта. Крім того, ви часто побачите * заголовки знищення * або * заголовки заходу сонця * - заголовки відповідей HTTP, такі як X-Api-Deprecated: true - використовуються для сигналізації, що кінцева точка буде вилучена в майбутньому, що дає розробникам час для міграції їх коду.

Зрозуміти ці відмінності є ключовим для ефективного спілкування у вашій команді і з зовнішніми клієнтами. Це не просто вибір стратегії версії; це про передачі * чому * ця стратегія була обрана і які зміни очікуються. Чистий журнал змін, що описує вплив кожної версії, є абсолютно необхідним - документуючи як функціональні доповнення, так і будь-які зміни.

Ось приклад, який демонструє, як можна використовувати версії URI у команді curl:

curl -H "Content-Type: application/v2+json" https://api.example.com/users?limit=10

Ця команда явно запитує API за допомогою версії 2, що забезпечує чіткість для сервера і всіх систем спостереження, що стежать за використанням API. Цей рівень деталізації є критичним для управління складністю сучасних API і забезпечення плавного переходу між версіями.