Byt API-version med kontroll över dataflödet

Planera bytet av ett programmeringsgränssnitt (API) utifrån de berörda dataflödena. Den nya slutpunkten är bara en del av övergången: även fält, behörigheter och tolkning av svar måste passa det anropande systemet.

Kartlägg de berörda anroparna

I ett fiktivt företag skickar en kundportal och en nattlig import order till samma API. Att bara flytta portalen skulle lämna den andra anroparen kvar. Notera vilka funktioner varje anropare använder och vem som kan genomföra dess övergång. Använd den faktiska leverantörens information om ändringar och avveckling; ett versionsnummer innebär ingen allmängiltig tidsfrist för migrering.

Google AIP-180 skiljer mellan kompatibilitet för källkod, överföring och betydelse. Riktlinjen hjälper till att bedöma ändringar; den garanterar inte beteendet hos vilket externt API som helst.

Beskriv ändringen med ett genomarbetat exempel

I vårt exempel innehåller den gamla begäran text i fältet delivery_note. Den nya versionen förväntar sig texten under delivery_note.text. Båda ska överföra samma leveransanvisning, ”Tor B”. Att byta en URL eller lyckas ansluta räcker därför inte för övergången.

Kontrollera också hur fel och fortfarande pågående bearbetning återkopplas. En annan svarsstruktur kan påverka anroparen även om begäran fortfarande godtas.

Jämför gammalt och nytt under samma förutsättningar

Förbered en normal order och ett fall utan leveransanvisning i en lämplig testmiljö. Jämför de sparade måluppgifterna och den synliga återkopplingen. Klargör också om de använda åtkomstbehörigheterna omfattar båda versionerna. Verkliga order ska inte skickas genom två produktionsvägar för denna jämförelse.

Samordna bytet med öppna åtgärder

Ange från vilken punkt nya begäranden använder den nya vägen. Redan skickade men ännu obekräftade begäranden behöver en koppling så att en upprepning inte behandlas som en ny order. Avtala en återgång för nya inkommande begäranden och undersök separat vad som händer med redan skrivna data. Att återställa en URL gör inte dessa ändringar ogjorda.

Den gamla versionen kan tas bort från detta dataflöde när alla kartlagda anropare har gått över och öppna åtgärder har kopplats. Dokumentera det faktiskt kontrollerade läget utöver den nya versionsetiketten.

Källor

• Google AIP-180: Backwards compatibility