Bytt API-versjon uten å miste oversikten over dataflyten

Planlegg byttet av et programmeringsgrensesnitt (API) ut fra de berørte dataflytene. Det nye endepunktet er bare en del av overgangen: Felt, rettigheter og tolkning av svar må også passe til systemet som kaller.

Kartlegg de berørte kallende systemene

I en oppdiktet virksomhet sender en kundeportal og en nattlig import ordrer til samme API. Å flytte bare portalen ville etterlate det andre kallende systemet. Noter hvilke funksjoner hvert system bruker, og hvem som kan gjennomføre overgangen. Bruk den faktiske leverandørens opplysninger om endringer og avvikling; et versjonsnummer gir ingen allmenngyldig migreringsfrist.

Google AIP-180 skiller mellom kompatibilitet for kildekode, overføring og betydning. Retningslinjen hjelper med å vurdere endringer; den garanterer ikke oppførselen til et vilkårlig eksternt API.

Beskriv endringen med et gjennomarbeidet eksempel

I eksemplet vårt inneholder den gamle forespørselen tekst i feltet delivery_note. Den nye versjonen forventer teksten under delivery_note.text. Begge skal overføre samme leveringsanvisning, «Tor B». Å bytte en URL eller opprette forbindelse er derfor ikke nok til denne overgangen.

Kontroller også hvordan feil og fortsatt pågående behandling meldes tilbake. En annen svarstruktur kan påvirke systemet som kaller, selv om forespørselen fortsatt godtas.

Sammenlign gammelt og nytt under samme forhold

Forbered en vanlig ordre og et tilfelle uten leveringsanvisning i et egnet testmiljø. Sammenlign de lagrede måldataene og den synlige tilbakemeldingen. Avklar også om tilgangsrettighetene som brukes, dekker begge versjonene. Reelle ordrer bør ikke sendes gjennom to produksjonsveier for denne sammenligningen.

Samordne byttet med åpne handlinger

Fastsett fra hvilket punkt nye forespørsler bruker den nye veien. Allerede sendte, men ennå ubekreftede forespørsler trenger en kobling slik at en gjentakelse ikke behandles som en ny ordre. Avtal en tilbakevei for nye innkommende forespørsler, og undersøk separat hva som skjer med data som allerede er skrevet. Å tilbakestille en URL gjør ikke disse endringene om.

Den gamle versjonen kan fjernes fra denne dataflyten når alle kartlagte kallende systemer har gått over, og åpne handlinger er koblet. Dokumenter tilstanden som faktisk er kontrollert, i tillegg til den nye versjonsetiketten.

Kilder

• Google AIP-180: Backwards compatibility