Changelog API: co publikować i kto to czyta

Changelog API to datowany rejestr każdej zmiany, którą wywołujący mógłby zauważyć, napisany dla osób integrujących się z API, a nie dla zespołu, który je wydaje. Ta grupa odbiorców czyni go innym dokumentem niż changelog produktu: czytelnik decyduje, czy jego kod będzie działał za miesiąc. Większość zawodzi tak samo, będąc odfiltrowaną kopią wewnętrznego strumienia wydań, więc usunięte pole leży obok poprawki tekstu z tą samą wagą, i żadne z nich nie jest czytane.

Czym jest changelog API?

To publiczny, datowany dziennik zmian w interfejsie, przeciwko któremu inni napisali kod. Przydatny test, czy coś do niego pasuje, nie ma nic wspólnego z tym, jak duża była zmiana wewnętrznie. Pyta, czy poprawny wywołujący, napisany w zeszłym roku i niedotykany od tamtej pory, mógłby zachować się inaczej z jej powodu. Ten test dopuszcza pewne bardzo małe zmiany i wyklucza pewne bardzo duże.

Wszystko poniżej zakłada, że wywołujący jest spoza firmy i praktycznie nieosiągalny inaczej niż przez ten dokument. Gdy wywołującym jest inny zespół w tej samej firmie, rachunek zmienia się na tyle, że zasługuje na własne potraktowanie; wewnętrzne changelogi API opisuje, czego zamiast tego potrzebują ci odbiorcy.

Jak napisać przewodnik migracji API obejmuje ten ostatni dokument w całości; krótko mówiąc, to do niego powinien linkować wpis o niekompatybilnej zmianie, zamiast próbować go zastąpić.

Te pięć to osobne dokumenty z osobnymi cyklami życia. Powiadomienie o deprecjacji to obietnica z datą i również należy do changeloga, ale wpis changeloga pisze się raz, podczas gdy deprecjację śledzi się aż do jej sunsetu. Łączenie ich jest powodem, dla którego sunsety są przegapiane.

Co powinno znaleźć się w jednym wpisie?

Sześć rzeczy, a pierwsze trzy to te, których zwykle brakuje. Zmiana, sformułowana w kategoriach żądania lub odpowiedzi, a nie wewnętrznego komponentu. Czy łamie poprawnego wywołującego. Co musi zrobić wywołujący, w tym “nic”. Data wejścia w życie. Wersja lub wersje, których dotyczy. Link do przewodnika migracji, jeśli istnieje.

Wpis, który mówi “ulepszono endpoint accounts”, zawodzi we wszystkich sześciu. Wpis, który mówi “pole accounts.type zwraca teraz individual tam, gdzie wcześniej zwracało personal; istniejące wartości pozostają niezmienione dla kont utworzonych przed 2 września; nie jest wymagane żadne działanie, chyba że porównujesz ten ciąg znaków”, odpowiada na wszystkie sześć w jednym zdaniu.

Kategoryzujcie wpisy według konsekwencji, nie działu. Trzy etykiety niosą prawie całą wartość: breaking, additive i fixed. Semantic Versioning definiuje już precyzyjnie pierwsze dwie, a pożyczenie jego definicji zamiast wymyślania własnych oznacza, że czytelnik znający semver zna wasze etykiety. Keep a Changelog oferuje dłuższy zestaw, jeśli chcecie, a jego centralna zasada obowiązuje tu mocniej niż gdziekolwiek indziej: dziennik jest dla ludzi, a zrzut tytułów commitów nim nie jest.

Czym changelog API różni się od notatek wydania?

Notatki wydania opisują, co produkt potrafi teraz zrobić. Changelog API opisuje, jaka jest teraz umowa. Ta sama wydana praca często tworzy wpis w obu, sformułowany inaczej, bo odbiorcy potrzebują różnych rzeczy: nowy format eksportu to funkcja dla użytkownika i nowa wartość enum dla wywołującego, który przełącza się na tym polu.

Praktyczną konsekwencją jest to, że te dwa nie mogą być tym samym strumieniem z innym stylem. Wywołujący subskrybujący wszystko, co wydajecie, w końcu się wypisze, a wtedy przegapi zmianę łamiącą. Jeśli publikujecie jeden strumień, filtrujcie go; jeśli publikujecie dwa, zawężcie ten dla API i nigdy nie wpuszczajcie do niego wpisu marketingowego. Porównujemy obie formy obok siebie w changelog vs notatki wydania.

Gdzie powinien mieszkać changelog API?

Obok dokumentacji referencyjnej, pod stabilnym adresem URL, z każdym wpisem indywidualnie adresowalnym przez fragment lub własną ścieżkę. Wywołujący linkują do wpisów w analizach incydentów i wewnętrznych zgłoszeniach, a wpis, do którego nie można linkować, ląduje wklejony jako zrzut ekranu.

Publikujcie go też jako wyjście czytelne maszynowo, oprócz strony. Strumień JSON zgodny ze specyfikacją JSON Feed lub strumień RSS nic nie kosztuje, gdy wpisy stają się danymi strukturalnymi, i to właśnie pozwala klientowi wbudować wasze zmiany we własny proces wydawniczy. To także część, która decyduje, czy ktoś na tym buduje. GitHub dokumentuje swoje wersje REST API tuż obok referencji z tego samego powodu: polityka wersjonowania jest częścią interfejsu.

Jak wygląda dobry wpis w praktyce?

Trzy wpisy z tego samego tygodnia, w formie opisanej powyżej:

2026-09-02  Breaking  v2
  `POST /invoices` odrzuca teraz `currency`, która nie pasuje do waluty
  konta klienta, zwracając 422 zamiast cicho konwertować. Wywołujący,
  którzy polegali na konwersji, muszą wysłać walutę konta. Dotyczy
  tylko v2; v1 pozostaje niezmienione do sunsetu 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` zyskuje znacznik czasu `settled_at`, null do momentu
  rozliczenia faktury. Nie wymaga działania. Klienci odrzucający
  nieznane pola powinni zostać zaktualizowani.

2026-08-31  Fixed  v2
  `GET /invoices?status=` zwracało pustą stronę zamiast 400 dla
  nieznanego statusu. Teraz zwraca 400 z akceptowanymi wartościami.
  Wywołujący z literówką wcześniej widzieli zero wyników, teraz widzą
  błąd.

Trzeci to typ najczęściej pomijany, bo wewnętrznie jest to poprawka błędu. Dla wywołującego, który zbudował retry wokół tej pustej strony, to zmiana zachowania, a wpis jest tym, co zapobiega zgłoszeniu do supportu. Etykieta mówi fixed, a treść mówi, co wywołujący mógłby zauważyć, co jest rozróżnieniem utrzymującym dziennik w uczciwości bez wyolbrzymiania każdej poprawki do zmiany łamiącej.

Jak wywołujący się subskrybują?

Dajcie im więcej niż jeden kanał, bo mają różne zadania. Strumień dla developera, który chce wszystkiego. E-mail dla kogoś, kto chce tylko zmian łamiących. Nagłówki odpowiedzi dla samego kodu, jedynego subskrybenta, który nigdy nie zapomina sprawdzić: nagłówek Sunset zdefiniowany w RFC 8594 umieszcza datę wycofania w odpowiedzi, gdzie biblioteka klienta może ją zalogować.

Kanał, który najczęściej pomija większość zespołów, to bezpośredni. Jeśli wywołujący używał w zeszłym tygodniu pola, które zmieniacie, wiecie, kto to jest, a e-mail do tych kont jest wart więcej niż jakakolwiek transmisja ogólna. To ta sama dyscyplina, co zamykanie pętli feedbacku klienta, zastosowana do zmiany, o którą nikt nie prosił: dotknięte osoby są informowane indywidualnie, a wszyscy pozostali otrzymują strumień. Webhook to czwarty kanał z własnym trybem awarii, który warto znać, zanim się na nim polega: changelogi webhooków opisuje, dlaczego zmiana payloadu tam psuje się po cichu, bez wywołującego, który mógłby odrzucić nowy kształt.

Jak napisać wpis dla zmiany łamiącej?

Zacznijcie od złamania, nie od powodu. Wywołujący skanujący dziesięć wpisów musi w pierwszym zdaniu wiedzieć, czy ten będzie go kosztował pracę. Potem data, dotknięte wersje, migracja i termin, jeśli stare zachowanie znika zamiast się zmieniać.

Umieśćcie tę samą treść w powiadomieniu o deprecjacji, nagłówku odpowiedzi i bezpośrednim e-mailu, sformułowaną spójnie, i dajcie wszystkim czterem tę samą datę. Rozbieżność między nimi to błąd, który zmienia zaplanowaną zmianę w incydent, bo wywołujący, który przeczytał tylko jeden z nich, działa według złej daty. Czym jest zmiana łamiąca omawia samą decyzję, a jak deprecjonować API omawia harmonogram, który następuje potem.

W changeloop zmiana API staje się wpisem, gdy pull request zostaje scalony, ktoś edytuje i zatwierdza szkic, a wpis publikuje się na strumieniu i w widżecie dokładnie w momencie, gdy wywołujący, którego opinia z widżetu stała się zgłoszeniem na GitHubie zamykanym przez ten pull request, zostaje o tym poinformowany w tym zgłoszeniu. Krok recenzji jest tu tym, co się liczy: changelog API to dokument umowny, i żaden szkic nie powinien dotrzeć do wywołującego bez przeczytania przez człowieka.

FAQ

Czy każda zmiana API potrzebuje wpisu changeloga? Każda zmiana, którą poprawny wywołujący mógłby zauważyć, tak, w tym te uważane przez was za wewnętrzne. Zmiany bez obserwowalnego efektu na żądanie lub odpowiedź nie, a dodawanie ich uczy czytelników pobieżnego czytania.

Czy changelog API powinien mieszkać w dokumentacji, czy na stronie marketingowej? W dokumentacji, tuż obok referencji. Czytelnik zazwyczaj już tam jest, a changelog na stronie marketingowej ma tendencję zdobywać odbiorców, dla których nie został napisany.

Jak daleko wstecz powinien sięgać? Bez ograniczeń. Wpisy są cytowane lata później w analizach incydentów, a obcięty dziennik łamie te linki. Paginujcie zamiast przycinać.

Czy potrzebuję osobnego changeloga dla każdej wersji API? Nie, jeden dziennik z polem wersji na wpis jest łatwiejszy do czytania i przeszukiwania. Filtrowanie według wersji to funkcja strony, nie powód do dzielenia dokumentu.

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