Versjoner og kompatibilitet

API-et har én hovedversjon, /v1, og den bare vokser. En integrasjon som skrives i dag, fortsetter å virke etter hvert som nye funksjoner kommer: Ingenting den bygger på, får nytt navn, fjernes eller får ny betydning.

Versjonsnummeret

API-et har et versjonsnummer som 1.62.0. Det endres ved hver utgivelse:

• delversjonen øker når noe legges til: en operasjon, et felt, en hendelse;
• feilrettingsversjonen øker når en beskrivelse eller en meldingstekst rettes og ingenting annet endres.

Du kan når som helst lese hvilken versjon en adresse betjener:

GET /v1/health har også en version, men det er versjonen av Sursa-utgivelsen som betjener adressen, ikke versjonen av API-et.

Du velger ikke delversjon: Hver forespørsel betjenes av den gjeldende. Takket være reglene nedenfor er det trygt.

Hva som kan endres i /v1

Disse endringene kan komme i hvilken som helst delversjon. Skriv integrasjonen din slik at de ikke får den til å slutte å virke:

• Nye operasjoner.
• Nye valgfrie parametere og felt i forespørsler. Forespørsler uten dem oppfører seg som før.
• Nye felt i svar, objekter og hendelser.
• Nye enum-verdier i svar, for eksempel en ny kortstatus eller en ny hendelsestype.
• Nye feilkoder og nye headere i svar.
• Grenser som blir mindre strenge: en større maksimal lengde, et bredere intervall.
• Omformulerte message-tekster i feil og omformulerte beskrivelser.

Hva koden din må tåle

• Ignorer felt du ikke kjenner. Koden skal ikke feile når et svar har flere felt enn du forventer, og ikke bruke strenge skjemaer som avviser dem.
• Godta enum-verdier du ikke kjenner. Hver enum i et svar kan vokse. Behandle en ukjent verdi som «annet» i stedet for som en feil.
• Hopp over hendelsestyper du ikke kjenner, både i webhooks og i strømmer.
• Håndter ukjente feilkoder etter HTTP-statusen: Se Feil.
• Ikke gjør koden avhengig av rekkefølgen på feltene i JSON-objekter eller av den nøyaktige teksten i meldinger.

Hva som aldri endres i /v1

• En bane, en parameter, et felt eller en enum-verdi får aldri nytt navn og fjernes aldri.
• Typen til et felt endres aldri, og et felt får aldri en ny betydning, for eksempel nye enheter.
• En forespørsel som godtas i dag, avvises ikke senere.
• Statuskoden for et vellykket svar forblir den samme.
• Feilkodene beholder betydningen sin, og feltet detail i feilsvar beholder formen sin.
• Hendelsestyper får aldri nytt navn og fjernes aldri, og data i dem får bare nye felt.

Inkompatible endringer

Hvis det noen gang blir behov for en inkompatibel endring, utgis den som en ny hovedversjon, for eksempel /v2, ved siden av /v1. /v1 fortsetter å virke uendret, og de to kjører side om side.

Når en rute skal fases ut:

1. Den merkes som deprecated i spesifikasjonen og føres opp i endringsloggen med datoen den skal slås av.
2. Svarene fra den har headerne Deprecation: true og Sunset: <date>.
3. Den fortsetter å virke i minst 180 dager etter kunngjøringen. Organisasjoner med API-nøkler som bruker den, får skriftlig beskjed minst 90 dager i forveien.
4. Etter utfasingsdatoen svarer den 410 med koden api.gone i ytterligere 90 dager.

Følg med på headeren Deprecation i loggene eller overvåkingen din: Den er det tidligste signalet om at en rute du bruker, er på vei ut.

Holde seg oppdatert

Portalens endringslogg viser hver utgivelse med det som ble lagt til, og det som ble foreldet. Før du oppgraderer integrasjonen din, sammenligner du koden med oppføringene siden versjonen du bygde den mot.