Вимкнути веб-API: кращі практики?

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

Які є найкращі практики для депресирування старих веб-програм?

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

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

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

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

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

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

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

Більшість використовуваних нами веб-API (від компаній, таких як Google, Yahoo! та Microsoft) мають період «заходу сонця». Розробники інформуються протягом розумного часу (скажімо 3-6 місяців) про функції, які будуть амортизовані, щоб дати їм заздалегідь багато часу на оновлення.

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

Також непогано використовувати нумерацію версій, щоб ви могли сказати, що, наприклад, "версія 3 скоро знеціниться, тому переконайтеся, що ваш код працює з версією 4" і т. Д. Таким чином люди знають, що якщо їх програма працює з версією 4 тоді вони готові до заходу сонця.

Додаткова інформація з точки зору процесу:

• Спілкуйтеся з усіма зацікавленими сторонами : надайте іншим командам та споживачам API чітке та стисле повідомлення про причину знецінення API, стратегію, деталі плану та розкладу, значення версії та альтернативи, встановіть HTTP відповідно.

• План і графік : На плані ви повинні мати ключові основні етапи та цільову дату закінчення припинення роботи. Ви повинні попросити споживачів того ж і вказати дати, коли вони припинять виклик. Організуйте чергову зустріч, щоб відстежувати процес та підтримувати споживачів.

• Версії та надання альтернативних варіантів : Версія може допомогти показати зміни в основних релізах та створити стратегію припинення API.

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

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

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

Постарайтеся уникати видалення функціональних можливостей, не надаючи альтернативи - це зробить деяких ваших користувачів нещасними.