Fire versioner
Dokumentationen har en versionsbetegnelse, som fortæller, hvilket indhold der er tale om. Partnerstien /v1 beskriver den eksterne kontraktprofil. Apprevisionen beskriver den konkrete app, Hours har gennemgået. Sandboxgenerationen beskriver appens aktuelle syntetiske testdatasæt.
En ny dokumentationsrettelse kræver ikke nødvendigvis et nyt kundegrant. En ny apprevision kan derimod ændre adgangsgrundlaget. En sandboxnulstilling giver nye testreferencer, men ændrer ikke i sig selv produktions-API-versionen.
Kontraktbrud skal være synlige
Et felt, som skifter enhed fra kroner til øre, er et alvorligt kontraktbrud, også selv om typen fortsat er number. Det samme gælder et svar, der tidligere var en kladde, men nu beskriver en udstedt faktura. Tekstforbedringer må ikke skjule ændret adfærd.
Udvidelser med nye obligatoriske felter, ændrede enums, nye scopes, strammere inputregler eller anderledes paginering skal vurderes som integrationsændringer. Et yderligere svarfelt kan også være følsomt: det er ikke automatisk sikkert at tilføje data, bare fordi mange klienter ignorerer ukendte felter.
Apprevisioner
Når en appprofil gemmes med en ændring, skal expected_revision matche den aktuelle version. Serveren opretter en ny revisionspost og tilbagekalder den tidligere adgang. Det er en streng model uden parallelle godkendte revisioner.
Planlæg derfor en ændring sammen med kunden og drift. En ny redirectadresse eller et udvidet formål skal ikke rulles ud midt i et ubemandet bogføringsjob uden en plan for reautorisation. Der tilbydes ikke en migrationsperiode med to aktive revisionsgrants.
Token- og nøglelevetid
Et kortlivet access-token er ikke API-versionering. Tokenrotation skal kunne ske inden for samme kontrakt og grant, mens tilbagekaldelse stopper adgangen. Rotér et secret ved tab eller mistanke om kompromittering; vent ikke på næste produktrelease.
Ved en genoprettet grant kan gamle idempotensnøgler tilhøre et andet adgangsgrundlag. Partner-API'et returnerer en konflikt frem for at udlevere den gamle operationskvittering gennem den nye grant. Integrationen skal afklare sådanne hændelser, ikke skabe en ny økonomisk handling ukritisk.
Dokumentationen følger API'et
De interne referencesider angiver deres kilde. Partnerkontrakten genereres og testes sammen med gatewayens input- og outputmodeller. En API-side må ikke beskrive en ønsket fremtidig funktion som en eksisterende route uden en tydelig status.
Ved en opdatering afstemmes kodeeksempler, OpenAPI, Markdown og MCP-indhold. En gammel MCP-installation kan ellers fortsætte med at anbefale en udfaset kontrakt, selv om websiden er opdateret. Brug en pin og en kontrolleret distributionsproces.
Udfasning kræver en aftalt proces
Der er ikke fastsat en bestemt garanti for varsling eller supportperiode. Sådanne løfter skal fremgå af den konkrete service- og partneraftale. Dokumentationen opfinder ikke en garanti på 30, 90 eller 180 dage.
Den praktiske proces skal identificere berørte apps, give et præcist ændringsnotat, tilbyde et testforløb og kunne måle, om gamle klienter fortsat kalder den udfasede kontrakt. Stop for en version må ikke blive et tavst fallback til et bredere internt API.