Versiuni și compatibilitate

API-ul are o singură versiune majoră, /v1, care doar crește. O integrare scrisă astăzi funcționează în continuare pe măsură ce apar funcții noi: nimic din ce folosește nu este redenumit, nu este eliminat și nu primește un sens nou.

Numărul versiunii

API-ul are un număr de versiune, de exemplu 1.62.0. Acesta se schimbă la fiecare lansare:

• numărul versiunii minore, când se adaugă ceva: un endpoint, un câmp, un eveniment;
• numărul de corecție (patch), când se corectează o descriere sau textul unui mesaj și nimic altceva nu se schimbă.

Puteți afla oricând versiunea servită de o adresă:

GET /v1/health are și el un câmp version, dar acesta este versiunea lansării Sursa care servește adresa, nu versiunea API-ului.

Nu alegeți o versiune minoră: fiecare cerere este servită de versiunea curentă. Datorită regulilor de mai jos, acest lucru este sigur.

Ce se poate schimba în /v1

Aceste modificări pot apărea în orice versiune minoră. Scrieți integrarea astfel încât să nu o strice:

• Endpointuri noi.
• Parametri și câmpuri de cerere noi, opționale. Cererile fără ele se comportă ca înainte.
• Câmpuri noi în răspunsuri, obiecte și evenimente.
• Valori noi ale enumerărilor din răspunsuri, de exemplu un status nou al fișei sau un tip nou de eveniment.
• Coduri de eroare noi și antete de răspuns noi.
• Limite care devin mai puțin stricte: o lungime maximă mai mare, un interval mai larg.
• Texte message ale erorilor și descrieri reformulate.

Ce trebuie să tolereze codul

• Ignorați câmpurile necunoscute. Nu eșuați când un răspuns are mai multe câmpuri decât vă așteptați și nu folosiți scheme stricte care le resping.
• Acceptați valorile de enumerare necunoscute. Orice enumerare dintr-un răspuns se poate extinde. Tratați o valoare necunoscută ca „altceva”, nu ca o eroare.
• Săriți peste tipurile de evenimente necunoscute, atât în webhookuri, cât și în fluxuri.
• Tratați codurile de eroare necunoscute după statusul HTTP: vedeți Erori.
• Nu depindeți de ordinea câmpurilor din obiectele JSON sau de textul exact al mesajelor.

Ce nu se schimbă niciodată în /v1

• O cale, un parametru, un câmp sau o valoare de enumerare nu sunt niciodată redenumite sau eliminate.
• Tipul unui câmp nu se schimbă niciodată, iar un câmp nu primește niciodată un sens nou, de exemplu alte unități.
• O cerere acceptată astăzi nu este respinsă mai târziu.
• Codul de status al unui răspuns reușit rămâne același.
• Codurile de eroare își păstrează sensul, iar câmpul detail al răspunsurilor de eroare își păstrează forma.
• Tipurile de evenimente nu sunt niciodată redenumite sau eliminate, iar data lor doar primește câmpuri noi.

Modificări incompatibile

Dacă vreodată va fi nevoie de o modificare incompatibilă, ea va fi lansată ca o nouă versiune majoră, de exemplu /v2, alături de /v1. /v1 continuă să funcționeze neschimbată, iar cele două rulează în paralel.

Când o rută urmează să fie retrasă:

1. Este marcată deprecated în specificație și apare în jurnalul modificărilor cu data la care va fi oprită.
2. Răspunsurile ei poartă antetele Deprecation: true și Sunset: <date>.
3. Funcționează în continuare cel puțin 180 de zile după anunț. Organizațiile ale căror chei API o folosesc sunt anunțate în scris cu cel puțin 90 de zile înainte.
4. După data retragerii, răspunde încă 90 de zile cu 410 și codul api.gone.

Urmăriți antetul Deprecation în jurnale sau în monitorizare: este cel mai timpuriu semnal că o rută pe care o folosiți va dispărea.

Cum rămâneți la curent

Jurnalul modificărilor din acest portal enumeră fiecare lansare, cu ce s-a adăugat și ce a fost depreciat. Înainte de a actualiza propria integrare, comparați codul ei cu intrările apărute de la versiunea pentru care a fost scrisă.