Контроль версій REST API

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

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

1. Коли треба користувати версії?

Оновлювати API потрібно лише тоді, коли внесено критичні зміни.

Критичні зміни включають:

  • зміна формату даних відповіді для одного або кількох викликів
  • зміна типу запиту або відповіді (тобто зміна цілого числа на число з плаваючою точкою)
  • видалення будь-якої частини API.

Критичні зміни завжди мають призводити до зміни номера основної версії API або типу вмісту відповіді.

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

Однак може бути корисно відстежувати проміжні версії API, коли вносяться зміни для підтримки клієнтів, які можуть отримувати кешовані версії даних або можуть мати інші проблеми з API.

2. Як встановити версію REST API?

REST не передбачає будь-яких конкретних інструкцій щодо версії, але найбільш часто використовувані підходи поділяються на три категорії:

2.1. Версії позначені в URI

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

Версія не обов’язково вказується числом або вказується за допомогою синтаксису «v[x]».

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

2.2. Керування версіями за допомогою заголовка спеціального запиту

Спеціальний заголовок (наприклад, Accept-version) дозволяє зберігати ваші URI між версіями, хоча він фактично є дублікатом поведінки узгодження вмісту, реалізованої існуючим заголовком Accept.

2.3. Керування версіями за допомогою заголовка «Accept».

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

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

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

У реальному світі API ніколи не буде повністю стабільним. Тому важливо, як керувати цією зміною.

Добре задокументоване та поступове припинення використання API може бути прийнятною практикою для більшості API.

      0 0 голосів
      Рейтинг статті
      Підписатися
      Сповістити про


      Цей сайт використовує Akismet для зменшення спаму. Дізнайтеся, як обробляються ваші дані коментарів.

      0 Коментарі
      Старіші
      Новіші Найпопулярніші
      Вбудовані Відгуки
      Переглянути всі коментарі