Wygląda na to, że oryginalny plakat już działał skutecznie, ale nieoficjalnie wycofał swoje API (wszystko, co nazywane jest „starym API”). Jednak dopóki nie zostanie ogłoszone, a użytkownicy nie zostaną powiadomieni, że interfejs API jest przestarzały, nie jest on formalnie przestarzały.
Przestarzałe API jest tymczasowym, nieaktywnym etapem kodu. To ostatnie obrzędy. Jest to okres, w którym osoby adoptujące / konsumenci mogą zmienić konfigurację swoich aplikacji pod kątem nowszego interfejsu API i pożegnać się z nimi, nawiązując pokój z interfejsem API. Niektóre interfejsy API mogą pozostawać dłużej niż inne, ale w tym momencie wiemy, że ich czas nie jest długi.
Usunięte API to pogrzeb kodu. Nic więcej nie może zrobić, ale odpowiednio ułożony i odpowiednio upamiętniony.
Wielu programistów API i usług wybiera pogrzeby kodu zamiast wykonywania ostatnich obrzędów; Myślę jednak, że jest to nieco ryzykowne. Jeśli była jakaś obietnica usługi lub wsparcia złożona, gdy API / usługa została pierwotnie przyjęta lub przez odnowienie, możesz chcieć dotrzymać tego zobowiązania przez rozsądny okres przed przeprowadzeniem pogrzebu.
W przypadku bibliotek nieobsługiwanych uważam, że jedna główna wersja wydania, niezależnie od okresu, jest prawdopodobnie więcej niż akceptowalnym i uczciwym okresem gwarantowanej kompatybilności wstecznej. Poza tym zależy to od wpływu i lobbingu użytkowników, aby przedłużyć jego życie poza ten okres. I nie zdziw się, jeśli od czasu do czasu pojawią się zastrzeżenia z powodu niezastąpionych zależności stron trzecich, które utknęły w zawieszeniu i są powiązane z niektórymi wersjami niektórych platform.
Podejrzewam, że w przypadku usług warto przyjrzeć się okresowi sześciomiesięcznemu lub rocznemu, po prostu ze względu na rozbieżność między tym, kto i jak usługa może być konsumowana, a także odpowiednią wariancję cyklu rozwojowego od projektu konsumującego do projektu konsumującego - wiele projektów, które mogą pochłaniać twoją usługę, może nadal mieć duży projekt z góry i może zaplanować cykl wydawania dłuższy niż rok. Większość opinii deweloperów z zewnątrz sugerowałoby, że osoby z długimi harmonogramami są odpowiedzialne za dotrzymywanie czasów cyklu, a te projekty pochłaniające długi cykl powinny przyjąć szybszy cykl wydawania i może to być prawda. Ale ostatecznie data usunięcia jest czymś, co musisz negocjować z użytkownikami.
Dobrą, ale nie kuloodporną strategią wycofania może być ogłoszenie zapowiedzi wycofania, podkreślenie ram czasowych zamiaru usunięcia, wraz z prośbą o komentarz lub sprzeciw w formacie ankiety danych sekcji API. Jeśli nie masz listy kontaktów użytkowników, ponieważ Twoja usługa działa z [częściowo] anonimowym dostępem, możesz rozważyć przejrzenie dzienników dla częstych i aktywnych użytkowników i wysłać powiadomienie do hosta lub administratora domeny, aby przekazać dalej, jeśli uznają to za stosowne.
Większość interfejsów API, z których korzystam (takich firm jak Google, Yahoo! i Microsoft) ma okres „wygaśnięcia”. Deweloperzy są informowani w rozsądnym czasie (powiedzmy 3-6 miesięcy) o funkcjach, które zostaną wycofane, aby dać im dużo czasu na aktualizację.
Możesz dodać szczegóły dotyczące okresów zachodu słońca w swoich Warunkach korzystania z usługi lub innej dokumentacji, aby ludzie wiedzieli, jak to działa. Oznaczałoby to, że gdy ktoś zdecyduje się użyć Twojego interfejsu API, będzie wiedział, z którymi harmonogramami musi pracować. Na przykład możesz poinformować ludzi, że będą musieli aktualizować swój system raz w roku, z zachowaniem 4-miesięcznego okresu wypowiedzenia.
Dobrym pomysłem jest także stosowanie numeracji wersji, abyś mógł powiedzieć, że na przykład „wersja 3 zostanie wkrótce wycofana, więc upewnij się, że kod działa z wersją 4” itp. W ten sposób ludzie wiedzą, że jeśli ich aplikacja działa z wersją 4 wtedy są gotowi na zachód słońca.
źródło
Dodatkowe informacje z kąta procesu:
Komunikuj się ze wszystkimi zainteresowanymi stronami : Zapewnij innym zespołom i konsumentom API jasną i zwięzłą komunikację na temat powodów wycofania interfejsu API, strategii, szczegółów planu i harmonogramu, znaczenia wersji i alternatyw, odpowiednio ustaw HTTP.
Plan i harmonogram : w planie powinieneś mieć kluczowe etapy i docelową datę wycofania. Powinieneś poprosić konsumentów o to samo i podać daty, w których wycofają połączenie. Poprowadź regularne spotkanie w celu monitorowania procesu i wspierania konsumentów.
Wersjonowanie i zapewnianie alternatyw : Wersjonowanie może pomóc w pokazaniu zmian przełomowych w głównych wersjach i uczynić strategię wycofywania API.
Ustaw nagłówek Sunset HTTP Response : Nagłówki HTTP odgrywają techniczną część ostrzeżenia, konsumenci API powinni monitorować ten typ kodu, aby zrozumieć, kiedy API jest przestarzałe.
Monitoruj przed i po : Monitoruj swoich klientów i powiadamiaj każdego konsumenta, który nadal używa interfejsu API po pewnym okresie, jest użyteczną informacją, aby upewnić się, że nie przegapisz żadnego porzuconego oprogramowania.
źródło
Oprócz istniejących odpowiedzi należy usunąć zastępczy lub plan migracji podczas usuwania czegoś, aby użytkownicy mogli zaktualizować swój kod.
Staraj się unikać usuwania funkcji bez podawania alternatywy - to spowodowałoby, że niektórzy użytkownicy byliby niezadowoleni.
źródło