Versijos ir suderinamumas

API turi vieną pagrindinę versiją – /v1, ir ji tik plečiasi. Šiandien parašyta integracija veikia toliau, kai atsiranda naujų funkcijų: niekas, kuo ji remiasi, nepervadinama, nepašalinama ir negauna naujos prasmės.

Versijos numeris

API turi versijos numerį, pavyzdžiui, 1.62.0. Jis keičiasi su kiekviena išleista versija:

šalutinės versijos numeris – kai kas nors pridedama: operacija, laukas, įvykis;
pataisos numeris – kai pataisomas aprašas ar pranešimo tekstas ir daugiau niekas nesikeičia.

Kurią versiją aptarnauja adresas, galite sužinoti bet kada:

Kur	Kas
`GET /openapi.json`	specifikacijos `info.version`
Kiekvienas įvykių juostos įvykis ir kiekvienas webhook pranešimas	`api_version` – versija, kurios schemą atitinka `data`

GET /v1/health taip pat turi version, bet tai adresą aptarnaujančios Sursos išleistos versijos numeris, o ne API versija.

Šalutinės versijos nesirenkate: kiekvieną užklausą aptarnauja dabartinė. Dėl toliau aprašytų taisyklių tai saugu.

Kas gali keistis /v1

Šie pakeitimai gali atsirasti bet kurioje šalutinėje versijoje. Integraciją rašykite taip, kad jie jos nesugadintų:

Naujos operacijos.
Nauji nebūtini parametrai ir užklausos laukai. Užklausos be jų veikia kaip anksčiau.
Nauji laukai atsakuose, objektuose ir įvykiuose.
Naujos išvardijimų reikšmės atsakuose, pavyzdžiui, nauja kortelės būsena ar naujas įvykio tipas.
Nauji klaidų kodai ir naujos atsako antraštės.
Mažiau griežti limitai: didesnis didžiausias ilgis, platesnis intervalas.
Perrašyti klaidų message tekstai ir perrašyti aprašai.

Ką privalo toleruoti jūsų kodas

Ignoruokite nežinomus laukus. Nenutraukite darbo, kai atsake yra daugiau laukų, nei tikitės, ir nenaudokite griežtų schemų, kurios juos atmeta.
Priimkite nežinomas išvardijimų reikšmes. Kiekvienas atsako išvardijimas gali plėstis. Nežinomą reikšmę vertinkite kaip „kita“, o ne kaip klaidą.
Praleiskite nežinomus įvykių tipus – ir webhook pranešimuose, ir srautuose.
Nežinomus klaidų kodus apdorokite pagal jų HTTP būseną: žr. Klaidos.
Nepriklausykite nuo laukų tvarkos JSON objektuose ar nuo tikslaus pranešimų teksto.

Kas niekada nesikeičia /v1

Kelias, parametras, laukas ar išvardijimo reikšmė niekada nepervadinami ir nepašalinami.
Lauko tipas niekada nesikeičia, ir laukas niekada negauna naujos prasmės, pavyzdžiui, naujų matavimo vienetų.
Šiandien priimama užklausa vėliau nebus atmesta.
Sėkmingo atsako būsenos kodas nesikeičia.
Klaidų kodai išlaiko savo prasmę, o klaidų atsakų laukas detail – savo formą.
Įvykių tipai niekada nepervadinami ir nepašalinami, o jų data tik gauna naujų laukų.

Nesuderinami pakeitimai

Jei kada nors prireiktų nesuderinamo pakeitimo, jis bus išleistas kaip nauja pagrindinė versija, pavyzdžiui, /v2, šalia /v1. /v1 toliau veiks nepakitusi, o abi versijos veiks lygiagrečiai.

Kai maršrutas bus nutraukiamas:

Specifikacijoje jis pažymimas deprecated ir įrašomas į pakeitimų žurnalą su data, kada bus išjungtas.
Jo atsakuose yra antraštės Deprecation: true ir Sunset: <date>.
Jis veikia dar bent 180 dienų po paskelbimo. Organizacijoms, kurių API raktai jį naudoja, apie tai raštu pranešama likus bent 90 dienų.
Po nutraukimo datos jis dar 90 dienų grąžina 410 su kodu api.gone.

Stebėkite antraštę Deprecation savo žurnaluose ar stebėsenos sistemoje: tai ankstyviausias signalas, kad jūsų naudojamas maršrutas išnyks.

Kaip sekti pakeitimus

Šio portalo pakeitimų žurnale išvardytos visos išleistos versijos: kas pridėta ir kas paskelbta pasenusiu. Prieš atnaujinant savo integraciją, palyginkite jos kodą su įrašais nuo tos versijos, kuriai ji buvo kurta.