Versionering

Versionen står i stien, ikke i en header: /api/v1. Så kan den pinnes i en konfigurationsfil, den er synlig i en adgangslog, og den kan ikke blive væk under en proxy.

Hvad der er en v1-ændring

Additive ændringer bumper ikke. Vi lægger dem i v1 uden varsel:

• Et nyt felt i et svar
• Et nyt endpoint
• En ny valgfri query-parameter
• En ny værdi i et enum, for eksempel en ny sagsstatus
• En ny webhook-hændelse

Det betyder én ting for din klient, og det er hele kontrakten den anden vej:

Ignorér ukendte felter, og fald ikke over ukendte enum-værdier. En parser der afviser et svar fordi det havde et felt mere, vil gå i stykker en tilfældig onsdag.

I praksis: brug ikke en streng skemavalidering der afviser ekstra nøgler, og skriv default-grene i dine switch frem for at kaste en exception på en status du ikke kendte.

Hvad der bumper

Alt der kan få kode der virkede i går til at gøre noget forkert i dag:

• Et felt fjernes eller omdøbes
• Et felts type ændres, for eksempel fra streng til objekt
• En værdi betyder noget andet end før
• En hidtil valgfri parameter bliver påkrævet
• En standardværdi ændres

Sker det, kommer det som /api/v2, og v1 kører videre ved siden af. De er to stier i den samme applikation, ikke to udgivelser hvor den ene erstatter den anden.

Udfasning varsles i headere

Når en version er på vej ud, begynder svarene at bære det:

Header	Indhold
Deprecation	At denne version er udfaset
Sunset	Datoen hvor den holder op med at svare

Der går mindst seks måneder fra det første Sunset til versionen faktisk lukker. Log de to headere hvis du kan. Det er den billigste overvågning du kan få, og den er tavs indtil den betyder noget.

info.version er ikke sti-versionen

OpenAPI-dokumentet har sin egen info.version (1.0.0 i skrivende stund). Den beskriver dokumentet, ikke stien, og den kan tælle op når vi retter en beskrivelse eller tilføjer et felt.

Pin din integration på stien /api/v1. Brug info.version til at se om din lokale kopi af specifikationen er forældet, ikke som en kompatibilitetsgaranti.

Hent altid specifikationen fra kilden

curl -sS https://app.levano.io/api/v1/openapi.json -o levano-v1.json

Endpointet kræver ingen nøgle, netop fordi man skal kunne generere en klient før man har en. Det gør det også egnet til CI: hent specifikationen, sammenlign med den du genererede fra, og fejl bygget hvis noget du bruger er forsvundet. Så opdager du et brud i din pipeline i stedet for i produktion.

Den kopi der ligger her på portalen er et øjebliksbillede fra det tidspunkt siden blev bygget. Den er en nødløsning når den levende specifikation ikke kan hentes, ikke facit.

De to kontrakter versioneres hver for sig

/api/v1 og /api/kyc/v1 er to selvstændige kontrakter der tilfældigvis begge hedder v1. De kan bumpe uafhængigt, og de deler hverken tokens, pagineringsform eller udgivelsesplan. Antag ikke at en ændring i den ene siger noget om den anden.