Skift API-version med overblik over dataflowet

Planlæg skiftet af en programmeringsgrænseflade (API) ud fra de berørte dataflow. Det nye endepunkt er kun en del af overgangen: Felter, rettigheder og fortolkning af svar skal også passe til det kaldende system.

Registrér de berørte kaldende systemer

I en fiktiv virksomhed sender en kundeportal og en natlig import ordrer til samme API. Hvis kun portalen flyttes, efterlades det andet kaldende system. Noter for hvert system, hvilke funktioner det bruger, og hvem der kan gennemføre overgangen. Brug den faktiske udbyders oplysninger om ændringer og lukning; et versionsnummer fastlægger ikke en almengyldig migrationsfrist.

Google AIP-180 skelner mellem kompatibilitet for kildekode, overførsel og betydning. Retningslinjen hjælper med at vurdere ændringer; den garanterer ikke adfærden for et vilkårligt eksternt API.

Beskriv ændringen med et gennemarbejdet eksempel

I vores eksempel indeholder den gamle anmodning tekst i feltet delivery_note. Den nye version forventer teksten under delivery_note.text. Begge skal overføre samme leveringsanvisning, »Tor B«. Det er derfor ikke nok at udskifte en URL eller oprette forbindelse for at gennemføre overgangen.

Kontroller også, hvordan fejl og stadig igangværende behandling meldes tilbage. En anden svarstruktur kan påvirke det kaldende system, selv om anmodningen fortsat accepteres.

Sammenlign gammelt og nyt under samme betingelser

Forbered en normal ordre og et tilfælde uden leveringsanvisning i et egnet testmiljø. Sammenlign de gemte måldata og den synlige tilbagemelding. Afklar også, om de anvendte adgangsrettigheder dækker begge versioner. Til denne sammenligning bør virkelige ordrer ikke sendes ad to produktionsveje.

Afstem skiftet med åbne handlinger

Fastlæg, fra hvilket punkt nye anmodninger bruger den nye vej. Allerede sendte, men endnu ubekræftede anmodninger skal kunne knyttes til deres handling, så en gentagelse ikke behandles som en ny ordre. Aftal en tilbagevej for nye indgående anmodninger, og undersøg særskilt, hvad der sker med allerede skrevne data. At stille en URL tilbage gør ikke disse ændringer om.

Den gamle version kan fjernes fra dette dataflow, når alle registrerede kaldende systemer er flyttet, og åbne handlinger er knyttet korrekt. Dokumenter den faktisk kontrollerede tilstand ud over det nye versionsmærke.

Kilder

• Google AIP-180: Backwards compatibility