Changelog de API: ce publici și cine îl citește

Un changelog de API este registrul datat al fiecărei schimbări pe care ar putea-o observa un apelant, scris pentru cei care integrează API-ul, nu pentru echipa care îl lansează. Acest public îl face un document diferit de un changelog de produs: cititorul decide dacă codul lui va mai funcționa luna viitoare. Majoritatea eșuează în același fel, fiind o copie filtrată a unui flux intern de lansări, astfel încât un câmp eliminat stă lângă o corectură de text cu aceeași greutate, și niciuna nu e citită.

Ce este un changelog de API?

Este jurnalul public și datat al schimbărilor la o interfață împotriva căreia alții au scris cod. Testul util pentru a decide dacă ceva își are locul acolo nu are nicio legătură cu cât de mare a fost schimbarea intern. El întreabă dacă un apelant corect, scris anul trecut și neatins de atunci, s-ar putea comporta diferit din cauza ei. Acest test admite unele schimbări foarte mici și exclude unele foarte mari.

Tot ce urmează presupune că apelantul e din afara companiei și practic inaccesibil decât prin acest document. Când apelantul e o altă echipă din aceeași companie, calculul se schimbă suficient încât să merite un tratament propriu; changelog-uri de API interne acoperă de ce are nevoie acel public în schimb.

Cum scrii un ghid de migrare API acoperă integral acest ultim document; pe scurt, e ceea ce ar trebui să lege o intrare de schimbare incompatibilă, în loc să încerce să-l înlocuiască.

Cele cinci sunt documente separate cu cicluri de viață separate. O notificare de depreciere este o promisiune cu o dată, și aparține și changelog-ului, dar o intrare de changelog se scrie o dată, în timp ce o depreciere se urmărește până la sunset-ul ei. Confundarea lor este motivul pentru care sunset-urile sunt ratate.

Ce ar trebui să conțină o singură intrare?

Șase lucruri, iar primele trei sunt cele care lipsesc de obicei. Schimbarea, formulată în termeni de cerere sau răspuns, nu de componenta internă. Dacă rupe un apelant corect. Ce trebuie să facă apelantul, inclusiv “nimic”. Data la care a intrat în vigoare. Versiunea sau versiunile afectate. Un link către ghidul de migrare, dacă există unul.

O intrare care spune “endpoint de accounts îmbunătățit” eșuează la toate șase. O intrare care spune “câmpul accounts.type returnează acum individual unde înainte returna personal; valorile existente rămân neschimbate pentru conturile create înainte de 2 septembrie; nu e necesară nicio acțiune decât dacă comparați șirul de caractere” răspunde la toate șase într-o singură propoziție.

Categorizați intrările după consecință, nu după departament. Trei etichete duc aproape toată valoarea: breaking, additive și fixed. Semantic Versioning definește deja precis primele două, iar împrumutarea definițiilor sale în loc de a inventa altele proprii înseamnă că un cititor care cunoaște semver vă cunoaște etichetele. Keep a Changelog oferă un set mai lung dacă vreți, iar regula lui centrală se aplică aici mai puternic decât oriunde altundeva: jurnalul e pentru oameni, iar un revărsat de titluri de commit-uri nu este.

Prin ce diferă un changelog de API de note de lansare?

Notele de lansare descriu ce poate face produsul acum. Un changelog de API descrie care e acum contractul. Aceeași muncă lansată produce adesea o intrare în ambele, formulată diferit, pentru că publicurile au nevoie de lucruri diferite: un format nou de export e o funcție pentru un utilizator și o valoare enum nouă pentru un apelant care comută pe acel câmp.

Consecința practică este că cele două nu pot fi același flux cu un stil diferit. Un apelant abonat la tot ce lansați se va dezabona în cele din urmă, și atunci va rata schimbarea care rupe compatibilitatea. Dacă publicați un flux, filtrați-l; dacă publicați două, îngustați-l pe cel de API și nu lăsați niciodată o intrare de marketing să intre în el. Comparăm cele două forme alăturat în changelog vs note de lansare.

Unde ar trebui să locuiască un changelog de API?

Lângă documentația de referință, la o adresă URL stabilă, cu fiecare intrare adresabilă individual printr-un fragment sau prin propria cale. Apelanții leagă intrări în analizele de incidente și în tichetele interne, iar o intrare care nu poate fi legată ajunge lipită ca o captură de ecran în schimb.

Publicați-l și ca ieșire lizibilă de mașini, pe lângă o pagină. Un flux JSON care urmează specificația JSON Feed sau un flux RSS nu costă nimic odată ce intrările devin date structurate, și e ceea ce permite unui client să integreze schimbările voastre în propriul proces de lansare. Aceasta e și partea care decide dacă cineva construiește pe el. GitHub își documentează versiunile REST API chiar lângă referință din același motiv: politica de versionare face parte din interfață.

Cum arată o intrare bună în practică?

Trei intrări din aceeași săptămână, în forma descrisă mai sus:

2026-09-02  Breaking  v2
  `POST /invoices` respinge acum o `currency` care nu se potrivește cu
  moneda contului clientului, returnând 422 în loc să convertească
  silențios. Apelanții care se bazau pe conversie trebuie să trimită
  moneda contului. Afectează doar v2; v1 rămâne neschimbat până la
  sunset-ul din 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` primește un timestamp `settled_at`, null până când factura
  e achitată. Nu e necesară nicio acțiune. Clienții care resping
  câmpuri necunoscute ar trebui actualizați.

2026-08-31  Fixed  v2
  `GET /invoices?status=` returna o pagină goală în loc de un 400
  pentru un status necunoscut. Returnează acum 400 cu valorile
  acceptate. Apelanții cu o greșeală de tastare vedeau înainte zero
  rezultate, acum văd o eroare.

Al treilea e tipul cel mai des omis, pentru că intern e o corecție de bug. Pentru un apelant care a construit un retry în jurul acelei pagini goale, e o schimbare de comportament, iar intrarea e ceea ce previne tichetul de suport. Eticheta spune fixed, iar corpul spune ce ar putea observa un apelant, ceea ce e distincția care păstrează jurnalul onest fără a umfla fiecare corecție la o schimbare care rupe compatibilitatea.

Cum se abonează apelanții?

Dați-le mai mult de un canal, pentru că au sarcini diferite. Un flux pentru dezvoltatorul care vrea totul. E-mail pentru cel care vrea doar schimbări ce rup compatibilitatea. Header-e de răspuns pentru codul însuși, singurul abonat care nu uită niciodată să verifice: header-ul Sunset definit în RFC 8594 pune data de retragere în răspuns, unde o bibliotecă client o poate loga.

Canalul pe care majoritatea echipelor îl omit e cel direct. Dacă un apelant a folosit săptămâna trecută câmpul pe care îl schimbați, știți cine e, iar un e-mail către acele conturi valorează mai mult decât orice difuzare generală. E aceeași disciplină ca la închiderea buclei de feedback a clientului, aplicată unei schimbări pe care nimeni nu a cerut-o: persoanele afectate sunt anunțate individual, iar toți ceilalți primesc fluxul. Un webhook e un al patrulea canal cu propriul mod de eșec, bun de știut înainte să vă bazați pe el: changelog-uri de webhook acoperă de ce o schimbare de payload acolo se strică în tăcere, fără apelant care să respingă noua formă.

Cum scrii o intrare pentru o schimbare care rupe compatibilitatea?

Începeți cu ruptura, nu cu motivul. Un apelant care scanează zece intrări trebuie să știe din prima propoziție dacă aceasta îi va costa muncă. Apoi data, versiunile afectate, migrarea, și termenul limită dacă vechiul comportament dispare în loc să se schimbe.

Puneți același conținut în notificarea de depreciere, header-ul de răspuns și e-mailul direct, formulat consecvent, și dați-le tuturor patru aceeași dată. Diferența dintre ele e greșeala care transformă o schimbare planificată într-un incident, pentru că apelantul care a citit doar una dintre ele acționează la data greșită. Ce este o schimbare care rupe compatibilitatea acoperă decizia în sine, iar cum se depreciază un API acoperă calendarul care urmează.

La changeloop, o schimbare de API devine o intrare când pull request-ul e integrat, o persoană editează și aprobă ciorna, iar intrarea se publică pe flux și widget în același moment în care un apelant al cărui feedback din widget a devenit issue-ul GitHub închis de pull request e anunțat în acel issue. Pasul de revizuire e cel care contează aici: un changelog de API e un document contractual, și nicio ciornă nu ar trebui să ajungă la un apelant fără ca o persoană să o fi citit.

FAQ

Are nevoie fiecare schimbare de API de o intrare în changelog? Orice schimbare pe care un apelant corect ar putea-o observa, da, inclusiv cele pe care le considerați interne. Schimbările fără efect observabil asupra cererii sau răspunsului nu, iar adăugarea lor antrenează cititorii să treacă în viteză peste text.

Ar trebui changelog-ul de API să stea în documentație sau pe site-ul de marketing? În documentație, chiar lângă referință. Cititorul e de obicei deja acolo, iar un changelog pe site-ul de marketing tinde să câștige un public pentru care nu a fost scris.

Cât de mult în urmă ar trebui să meargă? Nelimitat. Intrările sunt citate ani mai târziu în analize de incidente, iar un jurnal trunchiat rupe acele linkuri. Paginați în loc să tăiați.

Am nevoie de un changelog separat pentru fiecare versiune de API? Nu, un singur jurnal cu un câmp de versiune pentru fiecare intrare e mai ușor de citit și de căutat. Filtrarea după versiune e o funcție a paginii, nu un motiv de a împărți documentul.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Documentație pentru dezvoltatori, Exemple de changelog