Versijas un saderība

API ir viena galvenā versija – /v1, un tā tikai paplašinās. Šodien uzrakstīta integrācija turpina darboties, kad parādās jaunas iespējas: nekas, uz ko tā paļaujas, netiek pārdēvēts, noņemts un neiegūst jaunu nozīmi.

Versijas numurs

API ir versijas numurs, piemēram, 1.62.0. Tas mainās ar katru laidienu:

apakšversijas numurs – kad kaut kas tiek pievienots: operācija, lauks, notikums;
labojuma versijas numurs – kad tiek izlabots apraksts vai ziņojuma teksts un nekas cits nemainās.

Versiju, ko apkalpo konkrēta adrese, varat nolasīt jebkurā laikā:

Kur	Kas
`GET /openapi.json`	specifikācijas `info.version`
Katrs notikumu plūsmas notikums un katrs webhook paziņojums	`api_version` – versija, kuras shēmai atbilst `data`

Arī GET /v1/health ir version, taču tā ir Sursas laidiena versija, kas apkalpo adresi, nevis API versija.

Apakšversiju jūs neizvēlaties: katru pieprasījumu apkalpo pašreizējā. Pateicoties tālāk aprakstītajiem noteikumiem, tas ir droši.

Kas var mainīties /v1 robežās

Šīs izmaiņas var parādīties jebkurā apakšversijā. Rakstiet integrāciju tā, lai tās to nesabojātu:

Jaunas operācijas.
Jauni neobligāti parametri un pieprasījuma lauki. Pieprasījumi bez tiem darbojas kā iepriekš.
Jauni lauki atbildēs, objektos un notikumos.
Jaunas uzskaitījumu vērtības atbildēs, piemēram, jauns kartītes statuss vai jauns notikuma tips.
Jauni kļūdu kodi un jaunas atbildes galvenes.
Limiti, kas kļūst mazāk stingri: lielāks maksimālais garums, plašāks diapazons.
Pārformulēti kļūdu message teksti un pārformulēti apraksti.

Kas jūsu kodam jāpanes

Ignorējiet laukus, kurus nepazīstat. Nepārtrauciet darbu ar kļūdu, ja atbildē ir vairāk lauku, nekā gaidāt, un neizmantojiet stingras shēmas, kas tos noraida.
Pieņemiet uzskaitījumu vērtības, kuras nepazīstat. Jebkurš uzskaitījums atbildē var paplašināties. Nezināmu vērtību uztveriet kā „cita“, nevis kā kļūdu.
Izlaidiet notikumu tipus, kurus nepazīstat, gan webhook paziņojumos, gan straumēs.
Nezināmus kļūdu kodus apstrādājiet pēc HTTP statusa: sk. Kļūdas.
Nepaļaujieties uz lauku secību JSON objektos vai uz precīzu ziņojumu tekstu.

Kas /v1 nemainās nekad

Ceļš, parametrs, lauks vai uzskaitījuma vērtība nekad netiek pārdēvēta vai noņemta.
Lauka tips nekad nemainās, un lauks nekad neiegūst jaunu nozīmi, piemēram, citas mērvienības.
Pieprasījums, kas tiek pieņemts šodien, vēlāk netiek noraidīts.
Veiksmīgas atbildes statusa kods paliek tas pats.
Kļūdu kodi saglabā savu nozīmi, un kļūdu atbilžu lauks detail saglabā savu formu.
Notikumu tipi nekad netiek pārdēvēti vai noņemti, un to data tikai papildinās ar jauniem laukiem.

Nesaderīgas izmaiņas

Ja kādreiz būs vajadzīgas nesaderīgas izmaiņas, tās tiks izlaistas kā jauna galvenā versija, piemēram, /v2, blakus /v1. /v1 turpina darboties nemainīts, un abas versijas darbojas paralēli.

Kad maršrutu paredzēts izbeigt:

Specifikācijā tas tiek atzīmēts kā deprecated un iekļauts izmaiņu žurnālā ar datumu, kad tas tiks atslēgts.
Tā atbildēs ir galvenes Deprecation: true un Sunset: <date>.
Tas turpina darboties vismaz 180 dienas pēc paziņojuma. Organizācijām, kuru API atslēgas to izmanto, par to rakstiski paziņo vismaz 90 dienas iepriekš.
Pēc darbības beigu datuma tas vēl 90 dienas atbild ar 410 un kodu api.gone.

Sekojiet galvenei Deprecation savos žurnālos vai uzraudzībā: tā ir agrākā zīme, ka jūsu izmantotais maršruts tiks izbeigts.

Kā sekot izmaiņām

Šī portāla izmaiņu žurnālā ir uzskaitīts katrs laidiens: kas pievienots un kas atzīmēts kā novecojis. Pirms atjaunināt savu integrāciju, salīdziniet tās kodu ar ierakstiem kopš versijas, kurai to veidojāt.