Постачальник API залишив поле amount числовим, але почав передавати копійки замість гривень. Запити проходять, помилок формату немає, а суми в системі-споживачі стали іншими. Це умовний приклад зміни значення даних без зміни типу. Щоб її виявити до релізу, потрібна домовленість про зміст поля та перевірка реальної операції.
Опишіть значення разом із форматом
Технічна схема відповідає на питання про типи й структуру. Контракт обміну має також пояснювати одиницю виміру, часовий пояс, допустиме порожнє значення та походження поля. Для суми уточніть валюту й спосіб округлення. Для дати визначте, яку подію вона позначає.
OpenAPI дає стандартний спосіб описати HTTP API. Це корисна основа для документації й інструментів перевірки. Бізнес-значення полів усе одно потрібно явно описати та перевірити. Наявність специфікації не є доказом правильної реалізації.
Знайдіть фактичних споживачів
Перелік інтеграцій у документації може бути неповним. Перед зміною поєднайте відомості про доступ, журнали викликів і підтвердження відповідальних команд. Відсутність недавніх запитів ще не доводить, що споживач більше не потрібний: він може запускатися лише під час закриття періоду.
Для кожного споживача визначте власника, потрібні поля та умову приймання. Якщо власника не знайшли, зафіксуйте це як невирішену залежність, а не як мовчазну згоду на реліз.
Перевірте три різні рівні
| Перевірка | Що вона показує | Чого не доводить |
|---|---|---|
| Відповідь API | Запит отримав відповідь | Правильність облікового запису |
| Схема | Формат відповідає контракту | Правильне бізнес-значення |
| Наскрізний сценарій | Результат у системі-споживачі | Поведінку всіх інших сценаріїв |
У нашому прикладі тест має пройти від вихідної суми через перетворення до збереженого запису. Додайте нуль, дробову частину, порожнє значення, повторну доставку й непідтримувану валюту. Очікування погоджує власник процесу; універсального набору для всіх інтеграцій немає.
Перехід і відновлення плануються разом
Можливі варіанти: нова версія API, окреме поле або узгоджений адаптер. Вибір залежить від кількості споживачів і того, чи можна оновити їх одночасно. Стару поведінку варто залишати лише з визначеним строком та відповідальним за завершення переходу.
Відкат коду не завжди виправляє вже записані суми. Окремо визначте, як знайти операції за періодом зміни, перевірити їх і виконати погоджене виправлення. Повторний запуск не має створювати нові бізнес-операції.
Що підготувати до наступного релізу
- Опис зміни формату та значення полів.
- Список споживачів із відповідальними.
- Приклади вхідних даних та очікуваних кінцевих записів.
- План переходу, перевірки після запуску й виправлення даних.
Digital Line використовує такий підхід під час проєктування інтеграцій. Можливості API конкретного продукту Intecracy Group, його версії та конфігурації перевіряються до вибору способу підключення.
Питання та відповіді
Чи завжди потрібна нова версія API?
Ні. Потрібен спосіб, який зберігає погоджену поведінку для чинних споживачів. Навіть додавання поля треба перевірити на їхніх правилах обробки.
Чи достатньо тесту на стороні постачальника?
Він потрібний, але не показує всіх перетворень у споживача. Наскрізна перевірка має дійти до бізнес-результату.
Джерело
OpenAPI Specification описує формат HTTP API. План переходу й приклад вище є редакційним методом Digital Line.