API-kontrakter: opdatér appen uden at knække gamle klienter

API-kontrakten er større end en URL

En API-kontrakt er det, en klient med rimelighed er afhængig af. Det er ikke kun endpoint og metode, men også felter, datatyper, standarder, fejl, sortering, sideinddeling, adgangskrav og den forretningsmæssige virkning af et kald.

Request

Metode, sti, headers, felter, typer, påkrævede værdier, grænser og autentifikation.

Svar

Statuskode, felter, typer, tomme værdier, fejlformat, rækkefølge og sideinddeling.

Adfærd

Hvad der oprettes eller ændres, standardvalg, dublethåndtering og om et kald kan gentages sikkert.

Forbrugere

Webfrontend, mobilapp, partnerintegration, webhookmodtager, rapportjob eller andet internt system.

OpenAPI kan beskrive HTTP-overfladen i et maskinlæsbart format, men dokumentet beviser ikke alene, at den kørende backend følger kontrakten. Specifikation, test og faktisk drift skal stemme overens.

Find ændringen, der ser lille ud, men bryder brugen

En breaking change er en ændring, som får en eksisterende klient til at sende noget, serveren ikke længere accepterer, forstå svaret forkert eller opleve en anden virkning. Google skelner blandt andet mellem teknisk format og den synlige betydning: JSON kan stadig være gyldig, selv om appens forventede adfærd er blevet brudt.

Gør den eksisterende kontrakt synlig

Start med den API, der faktisk kører. En ny OpenAPI-fil skrevet ud fra ønsket adfærd kan skjule samme problem som manglende dokumentation. Kortlæg de kritiske kald fra klientkode, netværkstrafik, serverruter og tests, og forbind hvert kald med en ejer.

• Navngiv forbrugerne: Hvilke frontends, apps, jobs eller virksomheder kalder endpointet, og hvordan opdateres de?
• Gem kontrakten med koden: Brug OpenAPI, JSON Schema, typer eller konkrete request- og responseksempler efter den eksisterende stack.
• Beskriv betydningen: Skriv hvad tom, manglende og ukendt betyder, og hvilke standarder serveren bruger.
• Beskriv fejl: Angiv relevante statuskoder, et stabilt fejlkodefelt og om klienten må prøve igen.
• Forbind med en version: Log commit eller release-id for både klient og backend, så en fejl kan knyttes til den kørende kombination.

Udrul kompatible ændringer i flere små skift

Når frontend og backend ikke kan skifte i præcis samme øjeblik, skal overgangsperioden være en bevidst tilstand. Gør serveren i stand til at forstå både gammel og ny klient, før klienten begynder at sende den nye form.

1. 1. Udvid uden at fjerne: Tilføj den nye mulighed, men behold gamle felter, endpoints og standardadfærd.
2. 2. Udgiv klienten: Lad den nye frontend eller integration bruge den nye form, mens den gamle stadig accepteres.
3. 3. Mål overgangen: Registrér kontrakt- eller klientversion uden at logge følsomme payloads, og find reelle kald til den gamle form.
4. 4. Fjern kontrolleret: Luk først gammel adfærd efter aftalt frist, kommunikation, nul forventet brug og et sidste kompatibilitetstjek.

Samme mønster kan bruges, uanset om API'et ligger i Azure Functions, Firebase Cloud Functions, en traditionel server eller en anden backend. Deploymentværktøjet ændrer ikke kravet om en sikker overgang.

Versionér ved reelle brud – ikke ved hver rettelse

En ny API-version er relevant, når den gamle kontrakt ikke kan bevares uden urimelig tvetydighed eller risiko. Microsoft beskriver flere mulige strategier, blandt andet version i sti, queryparameter eller header. Ingen af dem fjerner behovet for at drive, teste og senere udfase den gamle version.

• Vælg én tydelig mekanisme: Brug den, som passer til eksisterende klienter, routing, cache og gateway – og dokumentér den.
• Bevar sikkerheden: En gammel version skal stadig have rettighedskontrol, validering, rate limiting, logging og sikkerhedsrettelser.
• Sæt en ejer og udfasningsplan: Versionsnummeret må ikke blive permanent opbevaring for ukendt gammel kode.
• Pin eksterne API-versioner: Hvis en leverandør understøtter det, skal den valgte version være eksplicit og opgraderes efter leverandørens ændringslog og testvej.

Stripe er et konkret eksempel på en leverandør med dokumenterede API-versioner og en opgraderingsproces. Brug altid den aktuelle dokumentation for den integration, appen faktisk anvender; kopier ikke Stripes versioneringsmodel ukritisk til andre API'er.

Test kombinationerne, som kan mødes i drift

En test af ny frontend mod ny backend viser kun sluttilstanden. Overgangen kræver en lille kompatibilitetsmatrix. Hvis backend kan blive rullet tilbage uden frontenden, er den modsatte kombination også relevant.

• Validér requests og svar mod kontrakten, men test også statuskoder, standarder, sortering, tomme resultater og sideeffekter.
• Gem eksempler fra rigtige forretningsforløb som testdata uden produktionspersondata eller secrets.
• Lad relevante kontrakt- og integrationstests køre før deployment og stoppe en kendt inkompatibel ændring.
• Ved flere selvstændige forbrugere kan consumer-driven contract testing bruges til at verificere, at udbyderen stadig opfylder de interaktioner, forbrugerne faktisk forventer.

Udfas gammel adfærd med beviser

En kommentar med “deprecated” stopper ikke kald. Udfasning kræver en kendt ejer, synlig brug, en realistisk frist og en aftale med de forbrugere, I ikke selv kan opdatere. For en intern webapp kan perioden være kort; for kunders integrationer eller native apps kan den være væsentligt længere.

• Registrér endpoint, kontraktversion, klientversion, resultat, svartid og request-id – ikke hele følsomme payloads som standard.
• Skeln mellem legitim gammel trafik, overvågning, bots og glemte testmiljøer, før I konkluderer at en version bruges.
• Varsl berørte integrationsejere med ændring, migrationsvej, testmulighed og konkret ophørsdato.
• Alarmér på ny eller uventet gammel trafik efter udfasningen, og behold en kontrolleret nødplan hvis lukningen rammer en vigtig arbejdsgang.
• Fjern til sidst kode, dokumentation, tests, routing og ekstra adgang – ikke kun linket i brugerfladen.

Typiske fejl

• Frontend og backend udgives som ét øjeblik: Åbne faner og mobile klienter gør antagelsen falsk.
• Et felt omdøbes direkte: Den gamle klient leder stadig efter det oprindelige navn.
• Et nyt felt bliver påkrævet: Eksisterende requests mangler feltet og bliver afvist.
• Kun JSON-formen testes: Ny sortering, standardværdi eller sideinddeling ændrer resultatet uden en syntaksfejl.
• Versionering bruges som oprydning: Flere versioner drives permanent uden ejer, måling eller udfasningsdato.
• Gamle endpoints mister sikkerhedsrettelser: En bagudkompatibel vej bliver en ubeskyttet genvej.
• Dokumentationen skrives efter koden: Ingen automatisk kontrol opdager, at implementering og kontrakt er gledet fra hinanden.
• Payloads logges for at måle brug: Fejlsøgning skaber en ny risiko for persondata og secrets.

Tjekliste før API'et ændres i produktion

• ☐ Endpointets requests, svar, fejl, standarder, sortering og sideeffekter er beskrevet.
• ☐ Alle kendte web-, mobil-, job- og integrationsforbrugere har en ejer og opdateringsvej.
• ☐ Ændringen er klassificeret som kompatibel, adfærdsændrende eller breaking med en konkret begrundelse.
• ☐ Nye requestfelter er valgfri og bevarer hidtidig adfærd, når de mangler.
• ☐ Gamle felter, endpoints og fejlformer virker fortsat under overgangsperioden.
• ☐ Tidligere klient mod ny backend er testet på kritiske brugerrejser.
• ☐ Ny klient mod tidligere backend er testet, hvis delvis rollback er mulig.
• ☐ Kontrakt- og integrationstests kører mod den faktiske implementering før deployment.
• ☐ Versionsstrategi, ejer og udfasningsdato er dokumenteret, hvis et reelt brud kræver en ny version.
• ☐ Den gamle version beholder relevante sikkerhedskontroller og driftsalarmer.
• ☐ Brug af gammel kontrakt kan måles uden at logge følsomme payloads.
• ☐ Berørte eksterne forbrugere har fået migrationsvej, testmulighed og realistisk varsel.
• ☐ Stopkriterier, rollback og kontrol efter udgivelsen er aftalt med en navngiven ansvarlig.

Relaterede guides

Officielle kilder

Kompatibilitetsregler afhænger af protokol, klientbiblioteker og den konkrete integrationsaftale. Kilderne nedenfor dokumenterer de principper, guiden bygger på; kontrollér desuden dokumentationen for appens faktiske framework, gateway og eksterne leverandører før en produktionsændring.

• OpenAPI Initiative: OpenAPI Specification
• Google AIP-180: Backwards compatibility
• Microsoft Azure Architecture Center: API design og versionering
• Pact: Provider verification af forbrugerkontrakter
• Stripe: API upgrades og bagudkompatible ændringer