Versioner och kompatibilitet

API:et har en enda huvudversion, /v1, och den bara växer. En integration som skrivs i dag fortsätter att fungera när nya funktioner tillkommer: inget som den är beroende av byter namn, tas bort eller får en ny betydelse.

Versionsnumret

API:et har ett versionsnummer som 1.62.0. Det ändras vid varje release:

delversionen när något läggs till: en slutpunkt, ett fält, en händelse;
korrigeringsversionen (patch) när en beskrivning eller en meddelandetext rättas och inget annat ändras.

Du kan när som helst läsa vilken version en adress betjänar:

Var	Vad
`GET /openapi.json`	specifikationens `info.version`
Varje händelse i händelseflödet och varje webhookleverans	`api_version`, versionen vars schema `data` följer

GET /v1/health har också ett version, men det anger vilken version av Sursa som betjänar adressen, inte API:ets version.

Du väljer inte delversion: varje anrop betjänas av den aktuella. Tack vare reglerna nedan är det säkert.

Vad som kan ändras i /v1

De här ändringarna kan komma i vilken delversion som helst. Skriv din integration så att de inte får den att sluta fungera:

Nya slutpunkter.
Nya valfria parametrar och fält i anrop. Anrop utan dem fungerar som tidigare.
Nya fält i svar, objekt och händelser.
Nya uppräkningsvärden i svar, till exempel en ny kortstatus eller en ny händelsetyp.
Nya felkoder och nya svarshuvuden.
Gränser som blir mindre strikta: en längre maxlängd, ett bredare intervall.
Omformulerade message-texter i fel och omformulerade beskrivningar.

Vad din kod måste tåla

Ignorera fält som du inte känner till. Misslyckas inte när ett svar har fler fält än du väntar dig, och använd inte strikta scheman som avvisar dem.
Godta uppräkningsvärden som du inte känner till. Varje uppräkning i ett svar kan växa. Behandla ett okänt värde som ”övrigt” i stället för som ett fel.
Hoppa över händelsetyper som du inte känner till, både i webhookar och i strömmar.
Hantera okända felkoder utifrån deras HTTP-status: se Fel.
Var inte beroende av fältens ordning i JSON-objekt eller av meddelandenas exakta text.

Vad som aldrig ändras i /v1

En sökväg, en parameter, ett fält eller ett uppräkningsvärde byter aldrig namn och tas aldrig bort.
Ett fälts typ ändras aldrig, och ett fält får aldrig en ny betydelse, till exempel nya enheter.
Ett anrop som godtas i dag avvisas inte senare.
Statuskoden för ett lyckat svar förblir densamma.
Felkoderna behåller sin betydelse, och fältet detail i felsvar behåller sin form.
Händelsetyper byter aldrig namn och tas aldrig bort, och deras data får bara fler fält.

Bakåtinkompatibla ändringar

Om en inkompatibel ändring någon gång behövs släpps den som en ny huvudversion, till exempel /v2, bredvid /v1. /v1 fortsätter att fungera oförändrad, och de två körs sida vid sida.

När en väg ska tas ur bruk:

Den markeras som deprecated i specifikationen och listas i ändringsloggen med datumet då den stängs av.
Dess svar har huvudena Deprecation: true och Sunset: <date>.
Den fortsätter att fungera i minst 180 dagar efter meddelandet. Organisationer vars API-nycklar använder den meddelas skriftligen minst 90 dagar i förväg.
Efter slutdatumet svarar den 410 med koden api.gone i ytterligare 90 dagar.

Håll utkik efter huvudet Deprecation i dina loggar eller i övervakningen: det är den tidigaste signalen om att en väg som du använder håller på att försvinna.

Håll dig informerad

Portalens ändringslogg listar varje release med vad som lades till och vad som förklarades föråldrat. Innan du uppgraderar din egen integration jämför du dess kod med posterna sedan den version som du byggde den mot.