Versioonid ja ühilduvus

API-l on üks põhiversioon, /v1, ja see ainult kasvab. Täna kirjutatud integratsioon töötab edasi ka uute funktsioonide lisandudes: midagi, millele see tugineb, ei nimetata ümber, ei eemaldata ega anta sellele uut tähendust.

Versiooninumber

API-l on versiooninumber, näiteks 1.62.0. See muutub iga väljalaskega:

• alamversiooni number, kui midagi lisatakse: lõpp-punkt, väli, sündmus;
• paikversiooni number, kui parandatakse kirjeldust või teate teksti ja midagi muud ei muutu.

Aadressil teenindatavat versiooni saate igal ajal lugeda:

Ka lõpp-punktil GET /v1/health on väli version, kuid see on aadressi teenindava Sursa väljalaske versioon, mitte API versioon.

Te ei vali alamversiooni: iga päringut teenindab praegune versioon. Allpool toodud reeglite tõttu on see turvaline.

Mis võib /v1 piires muutuda

Need muudatused võivad tulla mis tahes alamversioonis. Kirjutage oma integratsioon nii, et need seda ei rikuks:

• Uued lõpp-punktid.
• Uued valikulised parameetrid ja päringu väljad. Päringud ilma nendeta käituvad nagu varem.
• Uued väljad vastustes, objektides ja sündmustes.
• Uued enum-väärtused vastustes, näiteks uus kaardi olek või uus sündmusetüüp.
• Uued veakoodid ja uued vastuse päised.
• Piirangud, mis muutuvad leebemaks: suurem maksimaalne pikkus, laiem vahemik.
• Vigade ümber sõnastatud tekstid message ja ümber sõnastatud kirjeldused.

Mida peab teie kood taluma

• Ignoreerige tundmatuid välju. Ärge laske koodil ebaõnnestuda, kui vastuses on rohkem välju, kui ootate, ja ärge kasutage rangeid skeeme, mis need tagasi lükkavad.
• Aktsepteerige tundmatuid enum-väärtusi. Iga enum-väli vastuses võib laieneda. Käsitlege tundmatut väärtust kui „muu“, mitte kui viga.
• Jätke tundmatud sündmusetüübid vahele nii veebihaakides kui ka voogudes.
• Käsitlege tundmatuid veakoode nende HTTP-oleku järgi: vt Vead.
• Ärge sõltuge väljade järjekorrast JSON-objektides ega teadete täpsest tekstist.

Mis /v1 piires kunagi ei muutu

• Teed, parameetrit, välja ega enum-väärtust ei nimetata kunagi ümber ega eemaldata.
• Välja tüüp ei muutu kunagi ja väli ei saa kunagi uut tähendust, näiteks uusi ühikuid.
• Täna aktsepteeritud päringut ei lükata hiljem tagasi.
• Eduka vastuse olekukood jääb samaks.
• Veakoodid säilitavad oma tähenduse ja veavastuste väli detail säilitab oma kuju.
• Sündmusetüüpe ei nimetata kunagi ümber ega eemaldata ja nende data saab ainult välju juurde.

Ühilduvust rikkuvad muudatused

Kui kunagi on vaja ühildumatut muudatust, avaldatakse see uue põhiversioonina, näiteks /v2, versiooni /v1 kõrval. /v1 töötab muutmata kujul edasi ja need kaks toimivad kõrvuti.

Kui marsruut kavatsetakse kasutusest kõrvaldada:

1. See märgitakse spetsifikatsioonis kui deprecated ja lisatakse muudatuste logisse koos kuupäevaga, mil see välja lülitatakse.
2. Selle vastused sisaldavad päiseid Deprecation: true ja Sunset: <date>.
3. See töötab edasi vähemalt 180 päeva pärast teadaannet. Organisatsioone, mille API-võtmed seda kasutavad, teavitatakse kirjalikult vähemalt 90 päeva ette.
4. Pärast kasutusest kõrvaldamise kuupäeva vastab see veel 90 päeva 410 koodiga api.gone.

Jälgige päist Deprecation oma logides või seiresüsteemis: see on varaseim märk, et teie kasutatav marsruut kaob.

Kursis püsimine

Selle portaali muudatuste logi loetleb kõik väljalasked koos sellega, mis lisati ja mis märgiti aegunuks. Enne oma integratsiooni uuendamist võrrelge selle koodi kirjetega alates versioonist, mille järgi selle ehitasite.