Versionare și depreciere

v1 este înghețat la lansarea generală

De la lansarea generală (GA), /api/v1 se schimbă doar aditiv:

operații noi;
membri opționali noi în corpul cererilor, parametri de query opționali noi;
membri noi în răspunsuri;
valori noi ale enumerărilor din răspunsuri;
coduri de eroare noi pentru situații noi.

Nimic din ce funcționează azi nu este eliminat, redenumit sau schimbat ca sens în v1. Până la lansarea generală API-ul se mai poate schimba; fiecare astfel de schimbare apare în changelog.

Ce trebuie să facă clientul tău

Ca să rămână compatibil cu schimbările aditive, un client trebuie:

să ignore membrii necunoscuți din răspunsuri (să nu eșueze din cauza lor, să nu respingă obiectul);
să accepte valori de enumerare necunoscute (un status necunoscut înseamnă „altceva”, nu o eroare);
să nu depindă de ordinea membrilor sau a elementelor, decât acolo unde referința spune că ordinea este definită;
să ia decizii după code-ul erorii, nu după textul pentru oameni.

Bibliotecile client și CLI-ul se comportă deja așa.

Depreciere

Când ceva trebuie eliminat, este întâi depreciat:

operația este marcată deprecated în referință, cu data după care poate fi eliminată (x-pluspanel-sunset);
răspunsurile ei au antetul Deprecation (RFC 9745) și antetul Sunset (RFC 8594) cu acea dată, plus un Link către această pagină cu rel="deprecation";
changelog-ul o numește, împreună cu ce o înlocuiește.

Data de sunset este la cel puțin 12 luni după anunț:

HTTP/1.1 200 OK
Deprecation: @1792368000
Sunset: Thu, 19 Oct 2028 00:00:00 GMT
Link: <https://pluspanel.net/docs/api/versioning/>; rel="deprecation"; type="text/html"

Înregistrează aceste antete în jurnalele tale când apar, ca o depreciere să nu te ia niciodată prin surprindere.

O versiune majoră nouă

Eliminările se fac doar într-o versiune majoră nouă, /api/v2. Când apare v2, v1 rulează în paralel cu ea cel puțin 12 luni, ca să migrezi în ritmul tău. Aceleași chei API funcționează pe amândouă.

Webhooks

Payload-urile webhook respectă aceleași reguli: tipuri noi de evenimente și membri noi în data pot apărea oricând; receptorii trebuie să ignore ce nu cunosc.