Навіть невелика зміна відповіді API може зламати клієнтський застосунок. Перед релізом перевірте контракт на реальних сценаріях. ЗАПИШІТЬ, ЩО ОБІЦЯЄ API Для кожної важливої операції збережіть метод, адресу, параметри, обов’язкові поля, типи та можливі помилки. OpenAPI дає формат для опису HTTP API, але наявність файла ще не доводить, що реалізація йому відповідає. Призначте власника опису та додайте посилання на нього до процедури релізу. ПЕРЕВІРТЕ НЕОЧЕВИДНІ ЗМІНИ Видалення поля легко помітити. Перейменування, перехід числа в рядок, нове значення переліку або зміна порожнього значення іноді помітні лише на боці клієнта. Навіть нове необов’язкове поле може не пройти надто суворий клієнтський парсер. Розділіть список на явно несумісні зміни та зміни, для яких потрібна перевірка конкретних споживачів. МІНІМАЛЬНИЙ НАБІР ПРИКЛАДІВ Підготуйте нешкідливі зразки: типовий результат, порожній список, відсутнє необов’язкове поле, помилка валідації та відповідь без доступу. Додайте приклад для кожної підтримуваної валюти або формату дати, якщо вони є частиною API. Проганяйте ці приклади через підтримувані клієнтські версії, а не тільки через новий сервер. Для платіжних інтеграцій використовуйте тестове середовище провайдера без реального списання. ПЛАН ДЛЯ СПОЖИВАЧІВ Якщо зміна несумісна, погодьте спосіб версіонування та строк переходу. Дата у внутрішньому завданні не є повідомленням користувачу API. Запишіть, кого попередили, де доступна нова документація й хто стежить за старими запитами. Рекомендації Microsoft щодо дизайну API розглядають версіонування як частину підтримки клієнтів; конкретну схему обирайте відповідно до свого продукту. Окремо визначте адресу документації та стабільний API-піддомен. Зручна доменна структура допомагає навігації, але не замінює сумісності контракту. Перед публікацією домену API-продукту перевірте і назву, і процес наступного оновлення. Зображення: нова AI-фотоілюстрація для цієї статті, концептуальна сцена, а не документальне фото. Каталог доменів: https://domainevery.com/uk/domains Першоджерела: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design https://spec.openapis.org/oas/latest.html
