Versioner og kompatibilitet

API’et har én hovedversion, /v1, og den vokser kun. En integration, der skrives i dag, bliver ved med at virke, efterhånden som nye funktioner kommer til: Intet, den bygger på, bliver omdøbt, fjernet eller får en ny betydning.

Versionsnummeret

API’et har et versionsnummer som 1.62.0. Det ændres ved hver udgivelse:

• delversionen, når noget tilføjes: en operation, et felt, en hændelse;
• rettelsesversionen, når en beskrivelse eller en beskedtekst rettes, og intet andet ændres.

Du kan til enhver tid aflæse den version, som en adresse leverer:

GET /v1/health har også en version, men det er versionen af den Sursa-udgivelse, der betjener adressen, ikke API’ets version.

Du vælger ikke en delversion: Alle anmodninger betjenes af den aktuelle. Takket være reglerne nedenfor er det sikkert.

Hvad der kan ændre sig i /v1

Disse ændringer kan komme i enhver delversion. Skriv din integration, så de ikke bryder den:

• Nye operationer.
• Nye valgfrie parametre og felter i anmodninger. Anmodninger uden dem opfører sig som før.
• Nye felter i svar, objekter og hændelser.
• Nye enum-værdier i svar, fx en ny kortstatus eller en ny hændelsestype.
• Nye fejlkoder og nye svarheadere.
• Grænser, der bliver mindre strenge: en større maksimal længde, et bredere interval.
• Omformulerede message-tekster i fejl og omformulerede beskrivelser.

Hvad din kode skal kunne tåle

• Ignorér felter, du ikke kender. Fejl ikke, når et svar har flere felter, end du forventer, og brug ikke strenge skemaer, der afviser dem.
• Acceptér enum-værdier, du ikke kender. Alle enums i et svar kan udvides. Behandl en ukendt værdi som »andet« og ikke som en fejl.
• Spring hændelsestyper over, som du ikke kender, både i webhooks og i streams.
• Håndtér ukendte fejlkoder ud fra deres HTTP-status: se Fejl.
• Gør dig ikke afhængig af felternes rækkefølge i JSON-objekter eller af beskedernes nøjagtige tekst.

Hvad der aldrig ændrer sig i /v1

• En sti, en parameter, et felt eller en enum-værdi bliver aldrig omdøbt eller fjernet.
• Et felts type ændres aldrig, og et felt får aldrig en ny betydning, fx nye enheder.
• En anmodning, der accepteres i dag, bliver ikke afvist senere.
• Statuskoden for et vellykket svar forbliver den samme.
• Fejlkoder beholder deres betydning, og feltet detail i fejlsvar beholder sin form.
• Hændelsestyper bliver aldrig omdøbt eller fjernet, og deres data får kun flere felter.

Ikke-kompatible ændringer

Hvis der en dag bliver brug for en ikke-kompatibel ændring, udgives den som en ny hovedversion, fx /v2, ved siden af /v1. /v1 bliver ved med at virke uændret, og de to kører side om side.

Når en rute skal udfases:

1. Den markeres som deprecated i specifikationen og står i ændringsloggen med den dato, hvor den bliver slået fra.
2. Dens svar har headerne Deprecation: true og Sunset: <date>.
3. Den bliver ved med at virke i mindst 180 dage efter varslingen. Organisationer, hvis API-nøgler bruger den, får skriftlig besked mindst 90 dage i forvejen.
4. Efter udfasningsdatoen svarer den 410 med koden api.gone i yderligere 90 dage.

Hold øje med headeren Deprecation i dine logge eller din overvågning: Det er det tidligste signal om, at en rute, du bruger, er på vej væk.

Sådan holder du dig orienteret

Portalens ændringslog viser hver udgivelse med det, der blev tilføjet, og det, der blev markeret som forældet. Før du opgraderer din egen integration, så sammenlign dens kode med posterne siden den version, du byggede den til.