Cum scrii un ghid de migrare API

Un ghid de migrare API este documentul care transformă o schimbare incompatibilă într-o listă de verificare în loc de o pană: ce s-a schimbat, ce trebuie făcut în privința asta, și până când. O intrare de changelog poate numi o schimbare incompatibilă în două propoziții; un ghid de migrare este ce deschide de fapt apelanta când acele două propoziții spun „asta te strică” și trebuie să știe exact ce să modifice. Publicarea intrării fără ghid e felul în care apelanta află despre o schimbare incompatibilă dintr-un tichet de suport în loc de din documentul scris ca să prevină exact asta.

Ce este un ghid de migrare API?

Un document pas cu pas care duce o apelantă de la forma veche a unui API la cea nouă, scris pentru cineva cu cod de schimbat, nu pentru cineva care încă decide dacă adoptă API-ul. Distincția contează: un ghid de migrare presupune o integrare existentă și trafic de producție existent, deci trebuie să acopere rollback-ul, migrarea parțială, și cum se știe dacă migrarea a reușit, nimic din toate astea nefiind necesar unui ghid pentru o primă integrare.

Un ghid de migrare stă de obicei între ultimele două: o notificare de depreciere pornește un ceas, iar ghidul de migrare este ce urmează apelanta înainte ca acel ceas să expire.

Când o schimbare are nevoie de ghid de migrare, nu doar de o intrare de changelog?

Când există mai mult de un pas între comportamentul vechi și cel nou, sau când schimbarea atinge suficiente puncte de apel încât apelanta beneficiază mai mult de un exemplu lucrat decât de o descriere. Ce e o schimbare incompatibilă, și cum o lansezi acoperă testul pentru dacă o schimbare e incompatibilă; dacă răspunsul e da, a doua întrebare e dacă remedierea e o editare de o linie sau o migrare adevărată. Un câmp redenumit poate fi gestionat de apelantă doar cu intrarea de changelog. O schimbare la autentificare, paginare sau gestionarea erorilor merită aproape mereu un ghid, pentru că codul de înlocuire corect nu e evident dintr-o descriere de o propoziție.

Ce trebuie să conțină un ghid de migrare?

Cinci lucruri, iar omiterea oricăruia dintre ele e felul în care un ghid devine o pagină pe care apelanta o citește o dată și apoi revine la încercare și eroare. Codul vechi, arătat așa cum ar apărea de fapt într-un proiect. Codul nou, arătat la fel, nu ca o descriere abstractă a diferenței. Ce se strică dacă nu se schimbă nimic, spus clar, pentru că „nimic” e un răspuns valid și comun pe care apelanta tot trebuie să-l audă explicit. O modalitate de a verifica dacă migrarea a funcționat, cum ar fi un câmp de răspuns sau un cod de status de verificat. Și un calendar: când încetează comportamentul vechi să funcționeze, și dacă ambele forme sunt disponibile între timp.

## Migrarea câmpurilor valutare de la float la integer (v3.0.0)

Înainte:
  { "amount": 19.99 }

După:
  { "amount": 1999 }  // cea mai mică unitate valutară (bani)

Ce se schimbă: `amount` e acum un număr întreg în cea mai mică
unitate a valutei contului. Codul care citește `amount` ca float va
citi o valoare de 100x prea mare începând cu 1 octombrie 2026.

Verifică: după migrare, o taxă de 19,99 ar trebui să se citească
`amount: 1999`, nu `amount: 19.99`.

Calendar: v2 continuă să returneze float-uri până la 15 ianuarie
2027. v3 returnează numere întregi de la lansare. Ambele versiuni
sunt live acum.

Fiecare din aceste cinci lucruri răspunde la o întrebare pe care apelanta ar trebui altfel s-o ghicească sau s-o pună suportului, și exact ăsta e costul real pe care îl economisește un ghid de migrare.

Cine ar trebui să-l scrie, și când?

Cine a proiectat schimbarea, chiar în momentul în care e lansată, nu o echipă de suport care îl reconstruiește mai târziu din tichete. Cine a luat decizia știe pe care părți ale comportamentului vechi nimeni n-ar fi trebuit să se bazeze și care erau un contract accidental; un ghid scris mai târziu de cineva fără acel context tinde fie să supraexplice evidentul, fie să rateze exact cazul limită care chiar strică oamenii. Ghidul și intrarea de changelog care anunță schimbarea incompatibilă ar trebui să apară împreună, cu intrarea legând către ghid în loc să-l repete.

Cum se leagă asta de versionare și de changelog-ul API?

Direct: un ghid de migrare e versiunea detaliată a ceea ce o intrare MAJOR în semantic versioning și changelog-ul tău rezumă doar într-o propoziție. Intrarea de changelog spune că o schimbare e incompatibilă și, aproximativ, ce s-a schimbat; ghidul de migrare e link-ul pe care ar trebui să-l poarte acea intrare. Changelog de API: ce publici și cine îl citește enumeră ghidul de migrare ca unul din cinci documente pe care le menține un API, fiecare răspunzând la o întrebare diferită; acesta e cel care răspunde la „cum trec de fapt de la A la B”, și își câștigă propria pagină tocmai pentru că acel răspuns e de obicei prea lung pentru o intrare de changelog.

Cât timp ar trebui să rămână publicat un ghid de migrare?

Cel puțin cât timp comportamentul vechi rămâne accesibil, și ideal și după. O apelantă care migrează cu optsprezece luni întârziere, după ce a ignorat trei notificări de depreciere, tot are nevoie de ghid, iar ștergerea lui în ziua în care comportamentul vechi e oprit garantează doar că apelanta care are cea mai mare nevoie de el nu îl găsește. Păstrează-l la un URL stabil și actualizează secțiunea de calendar în loc să retragi pagina. Ghidul Stripe pentru upgrade-uri e un exemplu public al tiparului: o singură pagină, ținută la zi lansare după lansare, în loc de un document nou pentru fiecare versiune care se învechește chiar din momentul în care apare următoarea. Propriul vostru ghid merită să fie la fel de ușor de găsit, lângă docs-urile pe care o apelantă le citește deja, nu îngropat într-o arhivă de blog.

FAQ

Are nevoie fiecare schimbare incompatibilă de un ghid de migrare? Nu. O schimbare pe care apelanta o poate rezolva doar cu intrarea de changelog, cum ar fi un singur câmp redenumit cu o înlocuire evidentă, nu are nevoie de un ghid separat. O schimbare care atinge mai multe puncte de apel sau necesită un exemplu lucrat, da.

Ar trebui un ghid de migrare să stea lângă documentația API sau în changelog? Lângă documentație, legat din intrarea de changelog. Intrarea e ce vede o abonată prima; ghidul e ce are nevoie odată ce decide să acționeze, și aparține lângă materialul de referință pe care apelanta îl folosește deja.

Care e diferența dintre un ghid de migrare și o notificare de depreciere? O notificare de depreciere spune că ceva va dispărea și până când. Un ghid de migrare sunt instrucțiunile despre ce să faci în privința asta. O notificare de depreciere fără un ghid de migrare legat îi dă apelantei un termen fără să-i spună cum să-l respecte.

Ar trebui documentate atât comportamentul vechi cât și cel nou în timpul unei ferestre de migrare? Da, pe aceeași pagină dacă e posibil, ca apelanta să vadă exact ce s-a schimbat în loc să-l reconstruiască din două documente separate scrise în momente diferite.

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