Jak napisać przewodnik migracji API

Przewodnik migracji API to dokument, który zamienia niekompatybilną zmianę w listę kontrolną zamiast awarii: co się zmieniło, co z tym zrobić, i do kiedy. Wpis w changelogu może nazwać niekompatybilną zmianę w dwóch zdaniach; przewodnik migracji to coś, co wywołująca faktycznie otwiera, gdy te dwa zdania mówią „to cię łamie”, a ona musi wiedzieć dokładnie, co zmienić. Publikowanie wpisu bez przewodnika to sposób, w jaki wywołująca dowiaduje się o niekompatybilnej zmianie z ticketu wsparcia zamiast z dokumentu napisanego, żeby temu zapobiec.

Czym jest przewodnik migracji API?

Dokument krok po kroku, który prowadzi wywołującą od starej formy API do nowej, napisany dla kogoś, kto ma kod do zmiany, nie dla kogoś, kto wciąż decyduje, czy w ogóle przyjąć API. Ta różnica ma znaczenie: przewodnik migracji zakłada istniejącą integrację i istniejący ruch produkcyjny, więc musi obejmować wycofanie zmian, częściową migrację, i sposób sprawdzenia, czy migracja się powiodła, czego nie musi pokrywać przewodnik pierwszej integracji.

Przewodnik migracji zwykle stoi między tymi dwoma ostatnimi: powiadomienie o deprecjacji uruchamia zegar, a przewodnik migracji to coś, za czym podąża wywołująca, zanim ten zegar wybije.

Kiedy zmiana potrzebuje przewodnika migracji, a nie tylko wpisu w changelogu?

Gdy między starym a nowym zachowaniem jest więcej niż jeden krok, lub gdy zmiana dotyka wystarczająco wielu punktów wywołania, że wywołująca skorzysta bardziej z przerobionego przykładu niż z opisu. Czym jest zmiana niekompatybilna, i jak ją wydać opisuje test na to, czy zmiana jest niekompatybilna; jeśli odpowiedź brzmi tak, drugie pytanie to, czy poprawka to edycja jednej linii, czy prawdziwa migracja. Zmienione nazwy pola wywołująca może obsłużyć samym wpisem w changelogu. Zmiana w uwierzytelnianiu, paginacji lub obsłudze błędów niemal zawsze zasługuje na przewodnik, bo poprawny kod zastępczy nie jest oczywisty na podstawie jednozdaniowego opisu.

Co musi zawierać przewodnik migracji?

Pięć rzeczy, i pominięcie którejkolwiek zamienia przewodnik w stronę, którą wywołująca czyta raz, a potem wraca do prób i błędów. Stary kod, pokazany tak, jak naprawdę wyglądałby w projekcie. Nowy kod, pokazany tak samo, nie jako abstrakcyjny opis różnicy. Co się zepsuje, jeśli nic się nie zmieni, powiedziane wprost, bo „nic” to ważna i częsta odpowiedź, którą wywołująca i tak musi usłyszeć wyraźnie. Sposób na sprawdzenie, czy migracja zadziałała, jak pole odpowiedzi lub kod statusu do sprawdzenia. I harmonogram: kiedy stare zachowanie przestaje działać, i czy obie formy są dostępne w międzyczasie.

## Migracja pól walutowych z float na integer (v3.0.0)

Przed:
  { "amount": 19.99 }

Po:
  { "amount": 1999 }  // najmniejsza jednostka waluty (grosze)

Co się zmienia: `amount` jest teraz liczbą całkowitą w najmniejszej
jednostce waluty konta. Kod czytający `amount` jako float odczyta
wartość 100x za dużą od 1 października 2026.

Weryfikacja: po migracji obciążenie 19,99 powinno czytać się jako
`amount: 1999`, nie jako `amount: 19.99`.

Harmonogram: v2 nadal zwraca float do 15 stycznia 2027. v3 zwraca
liczby całkowite od startu. Obie wersje są teraz aktywne.

Każda z tych pięciu rzeczy odpowiada na pytanie, które wywołująca musiałaby inaczej zgadywać lub zadać wsparciu, i dokładnie to jest realny koszt, który oszczędza przewodnik migracji.

Kto powinien go napisać, i kiedy?

Kto zaprojektował zmianę, w tym samym momencie, w którym jest wydawana, nie zespół wsparcia rekonstruujący ją później z ticketów. Kto podjął decyzję, wie, na których częściach starego zachowania nikt nie powinien był polegać, a które były przypadkową umową; przewodnik napisany później przez kogoś bez tego kontekstu ma tendencję albo do nadmiernego tłumaczenia oczywistości, albo do pominięcia tego jednego przypadku brzegowego, który naprawdę łamie ludzi. Przewodnik i wpis w changelogu ogłaszający niekompatybilną zmianę powinny wyjść razem, a wpis powinien odsyłać do przewodnika zamiast go powtarzać.

Jak to się ma do wersjonowania i changeloga API?

Bezpośrednio: przewodnik migracji to szczegółowa wersja tego, co wpis MAJOR w semantic versioning a twój changelog streszcza tylko w jednym zdaniu. Wpis w changelogu mówi, że zmiana jest niekompatybilna i z grubsza co się zmieniło; przewodnik migracji to link, który ten wpis powinien nieść. Changelog API: co publikować i kto go czyta wymienia przewodnik migracji jako jeden z pięciu dokumentów, które utrzymuje API, każdy odpowiada na inne pytanie; ten odpowiada na „jak faktycznie przejść z A do B”, i zasługuje na własną stronę właśnie dlatego, że ta odpowiedź jest zwykle za długa na wpis w changelogu.

Jak długo przewodnik migracji powinien pozostać opublikowany?

Co najmniej tak długo, jak stare zachowanie pozostaje osiągalne, a najlepiej i po tym. Wywołująca migrująca osiemnaście miesięcy za późno, po zignorowaniu trzech powiadomień o deprecjacji, nadal potrzebuje przewodnika, a usunięcie go w dniu wyłączenia starego zachowania gwarantuje tylko, że wywołująca, która najbardziej go potrzebuje, go nie znajdzie. Trzymaj go pod stabilnym adresem URL i aktualizuj sekcję harmonogramu, zamiast wycofywać stronę. Własny przewodnik po aktualizacjach Stripe to publiczny przykład tego wzorca: jedna strona, aktualizowana wydanie po wydaniu, zamiast nowego dokumentu na każdą wersję, który dezaktualizuje się, gdy tylko wyjdzie kolejna. Wasz własny przewodnik powinien znaleźć się w równie łatwym do znalezienia miejscu, obok dokumentacji, którą wywołująca już czyta, a nie zakopany w archiwum bloga.

FAQ

Czy każda niekompatybilna zmiana potrzebuje przewodnika migracji? Nie. Zmiana, którą wywołująca może rozwiązać samym wpisem w changelogu, jak jedno zmienione pole z oczywistym zastępstwem, nie potrzebuje osobnego przewodnika. Zmiana dotykająca wielu punktów wywołania lub wymagająca przerobionego przykładu, potrzebuje.

Czy przewodnik migracji powinien być przy dokumentacji API, czy w changelogu? Przy dokumentacji, z linkiem z wpisu w changelogu. Wpis to coś, co subskrybentka widzi jako pierwsze; przewodnik to coś, czego potrzebuje, gdy zdecyduje się działać, i należy obok materiałów referencyjnych, których wywołująca już używa.

Jaka jest różnica między przewodnikiem migracji a powiadomieniem o deprecjacji? Powiadomienie o deprecjacji mówi, że coś zniknie i do kiedy. Przewodnik migracji to instrukcje, co z tym zrobić. Powiadomienie o deprecjacji bez linkowanego przewodnika migracji daje wywołującej termin, nie mówiąc jej, jak go dotrzymać.

Czy stare i nowe zachowanie powinny być udokumentowane oba podczas okna migracji? Tak, na tej samej stronie, jeśli to możliwe, żeby wywołująca widziała dokładnie, co się zmieniło, zamiast składać to z dwóch osobnych dokumentów napisanych w różnych momentach.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Dokumentacja dla deweloperów, Przykłady changeloga