Версії API REST. У кожного API є своя версія

Версію API REST дуже часто вказувати в URL-адресі, зокрема на початку шляху, тобто щось на зразок:

POST /api/v1/accounts
GET /api/v1/accounts/details

Однак я не бачив жодного дизайну, де версія пов'язана з кожним API. Іншими словами, ми підтримуємо версію кожного API окремо. тобто:

POST /api/accounts/v2
GET /api/accounts/details/v3

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

Які недоліки використання цього стилю замість загального стилю?

— Інж.Фуад
джерело

Відповіді:

Те, що ви називаєте одиночними API REST, може називатися певним набором ресурсів або ресурсів API REST API . Ви також можете подивитися на це як REST API по функціональності . Такого програмного забезпечення, як будь-який тип програмного забезпечення, весь пакунок впорядкований / оновлений, а не окремі функції та ресурси

Ваше запитання мало б сенс у контексті, коли ресурси пакету REST API є модульними і настільки потенційно розроблені та розроблені окремо.

Тоді, наскільки я бачу, основними мінусами запропонованої угоди про іменування локатора ресурсів є:

Для користувача API це призведе до набагато складніших локаторів ресурсів, менш передбачуваних, менш запам'ятовуються та менш стабільних.
Для розробників (-ів) модулів зараз доведеться більше працювати з цією версією у власному локаторі ресурсів.
Зміни в локаторах ресурсів стають набагато частішими, наскільки є кілька оновлених модулів, так що вищезгадані мінуси експоненціальні ...

Створюючи API, однією з основних ваших цілей є спрощення використання ...

Можливо, ви знайдете кращий спосіб ввести неполадку зміни або навіть версію версії API REST з, можливо, заголовком HTTP?

Щоб дізнатися більше про підхід до заголовків HTTP, дивіться інші відповіді нижче та: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— ClemC
джерело

Ось ще кращий підхід: використовуйте узгодження вмісту для версії свого API з заголовками Content-Typeта Acceptзаголовками:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Щоб отримати іншу версію, просто попросіть її з іншим типом вмісту Accept. Таким чином, окремі версії, які підтримує ваш сервер, повністю не залежать від вашої структури URL-адрес. Один і той же сервер може підтримувати кілька версій, просто вибираючи, на яку відповідати, на основі Acceptзаголовка. Крім того, якщо ви хочете дотримуватися різних розгортань для різних версій, ви можете поставити проксі-сервер перед різними версіями служби, які вибрали, на яку потрібно пересилати запити на основі Acceptзаголовка.

Це також дозволяє підтримувати нові формати з різною семантикою (а не лише різні версії) на одних і тих же кінцевих точках. Наприклад, розміщення списку облікових записів /api/accountsможе означати створення пакету, і вам не потрібно буде створювати окрему кінцеву точку API для цього.

— Джек
джерело

omg, заголовок прийняття повинен бути найгіршим вибором сигналізації версії. якщо можете, скористайтеся заголовком версії, якщо можете, наприклад, URL-адреса, якщо потрібно (тобто маршрутизація AWS)

— Ewan

@Ewan Чому? Заголовок користувацької версії означає, що різні версії - це один і той же ресурс, не повідомляючи посередників, що вміст може бути різним. Проксі-сервер кешування не знає використовувати ваш заголовок, щоб не подавати кешовані відповіді v1 на запити v2.

— Джек

використовуйте заголовок змінної відповіді, якщо ви вже не використовуєте кеш-пам'ять для запитів api !. тип вмісту вже має сенс, підпорядкування його для приватного використання просто ускладнює життя споживачам

— Ewan

@Ewan Ось для чого і vndчастина, і +синтаксис типу: для позначення цього підтипу, що залежить від конкретного постачальника application/json. Саме для цього призначені типи вмісту. Ваш ресурс доступний у різних форматах. Ви просите клієнта вибрати той формат, який він хоче. Крім того, немає ніяких причин, коли запити API не можуть використовувати стандартну семантику кешування HTTP.

— Джек

якщо ви виправите помилку в myapi v2, ви не повертаєте новий тип mime.

— Еван

Головне, що якщо ви встановлюєте кожну кінцеву точку окремо, ви повинні мати можливість розгорнути кожну кінцеву точку окремо.

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

Якщо ви не оновлюєте версію, коли вносите зміни, оскільки "О, я майже впевнений, що моя зміна не вплине на це", ви потрапите в проблеми, коли помилитесь.

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

Якщо у вас немає єдиної версії API, це стає набагато складнішим.

— Еван
джерело