Van API-versie wisselen met zicht op de gegevensstroom

Plan de wijziging van een programmeerinterface voor toepassingen (API) vanuit de betrokken gegevensstromen. Het nieuwe eindpunt is maar een deel van de migratie: ook velden, rechten en de verwerking van antwoorden moeten bij het aanroepende systeem passen.

Breng de betrokken aanroepers in kaart

In een fictief bedrijf sturen een klantportaal en een nachtelijke import orders naar dezelfde API. Alleen het portaal migreren zou de tweede aanroeper achterlaten. Leg per aanroeper vast welke functies deze gebruikt en wie de migratie kan uitvoeren. Gebruik de wijzigings- en uitfaseringsinformatie van de daadwerkelijke aanbieder; uit een versienummer volgt geen algemeen geldende migratietermijn.

Google AIP-180 onderscheidt compatibiliteit van broncode, overdracht en betekenis. De richtlijn helpt wijzigingen te beoordelen; ze garandeert niet het gedrag van een willekeurige externe API.

Beschrijf de wijziging met een uitgewerkt voorbeeld

In ons voorbeeld bevat het oude verzoek tekst in het veld delivery_note. De nieuwe versie verwacht de tekst onder delivery_note.text. Beide moeten dezelfde afleverinstructie “Tor B” overbrengen. Alleen een URL vervangen of succesvol verbinding maken is daarom onvoldoende voor deze migratie.

Controleer ook hoe fouten en nog lopende verwerking worden teruggekoppeld. Een andere antwoordstructuur kan de aanroeper raken, hoewel het verzoek nog steeds wordt geaccepteerd.

Vergelijk oud en nieuw onder dezelfde omstandigheden

Bereid in een geschikte testomgeving een normale order en een geval zonder afleverinstructie voor. Vergelijk de opgeslagen doelgegevens en de zichtbare terugmelding. Ga ook na of de gebruikte toegangsrechten beide versies dekken. Echte orders horen voor deze vergelijking niet via twee productiepaden te worden verstuurd.

Stem de overstap af op openstaande handelingen

Leg vast vanaf welk punt nieuwe verzoeken het nieuwe pad gebruiken. Al verstuurde maar nog onbevestigde verzoeken hebben een koppeling nodig, zodat een herhaling niet als een nieuwe order wordt behandeld. Spreek een rollback af voor nieuw binnenkomende verzoeken en controleer apart wat er met al geschreven gegevens gebeurt. Een URL terugzetten maakt die wijzigingen niet ongedaan.

De oude versie kan uit deze gegevensstroom verdwijnen zodra alle vastgelegde aanroepers zijn gemigreerd en openstaande handelingen zijn gekoppeld. Documenteer de daadwerkelijk gecontroleerde toestand naast het nieuwe versielabel.

Bronnen

• Google AIP-180: Backwards compatibility