Versjonering

Hva som kan endre seg i versjon 1, hvordan en utfasing varsles, og hvor OpenAPI-dokumentet ligger.

Oversikt⁠

Versjonen står i stien, /api/v1. Versjon 1 vokser bare, så en klient du skriver mot den i dag, fortsetter å virke.

Hva som kan endre seg i versjon 1⁠

Vi kan legge til en operasjon, et felt i et svar, en valgfri parameter eller en enum-verdi, så se bort fra felt du ikke kjenner. Vi fjerner ikke et felt, gir det ikke nytt navn, endrer ikke en type og gjør ikke en valgfri parameter påkrevd. En slik endring ville blitt en versjon 2 på en ny sti.

Utfasing⁠

Før en operasjon fases ut, blir den markert som utgående, og svarene har tre headere.

Header	Betydning
`Deprecation`	Når operasjonen ble markert som utgående, som `@` og en Unix-tid i sekunder
`Sunset`	Når operasjonen slutter å virke, som en HTTP-dato
`Link`	Siden som sier hva som erstatter den, med `rel="deprecation"`

En operasjon som ble markert som utgående 1. januar 2027 og slutter å virke 1. juli 2027, ville svart med disse.

deprecation: @1798761600sunset: Thu, 01 Jul 2027 00:00:00 GMTlink: <https://attia.app/docs/api-versioning>; rel="deprecation"

Så lenge operasjonen har disse headerne, markerer OpenAPI-dokumentet den med deprecated: true. Logg headerne i klienten din, så en utfasing ikke kommer overraskende. Ingen operasjon i versjon 1 er markert som utgående i dag.

OpenAPI-dokumentet⁠

OpenAPI 3.1-beskrivelsen av versjon 1 er åpen og krever ingen nøkkel. Den lister alle operasjoner, parametere og felt, og du kan generere en klient fra den.

curl https://attia.app/api/v1/openapi.json