Een integratie kan succesvolle responses blijven retourneren en toch gegevens verkeerd verwerken. Een provider verandert de betekenis van een veld, een bedrijfsplatform biedt twee API-versies aan of een klant gebruikt een afwijkende authenticatieconfiguratie. Met een compatibiliteitsmatrix voor software-integraties leg je vast welke combinaties de applicatie ondersteunt, welke zijn gevalideerd en welke beperkingen gelden.
Het is geen lijst van alle bestaande producten en evenmin een belofte van universele werking. Het is een hulpmiddel om te bepalen wat je afdekt, hoe je afwijkingen opspoort en wie moet handelen wanneer een afhankelijkheid verandert. In PHP-applicaties kan de matrix de technische inventaris verbinden met geautomatiseerde tests, monitoring en wijzigingsprocedures.
Wat compatibiliteit in een integratie betekent
Compatibiliteit omvat meer dan de versie van een API. Het is verstandig om ten minste vijf dimensies te onderscheiden:
- Formaat: structuur van het verzoek en de respons, contenttypen, codering en serialisatie.
- Velden: namen, typen, verplichtheid, null-waarden, toegestane waarden en validatieregels.
- Semantiek: wat elke waarde betekent en in welke eenheden of tijdzone die wordt geïnterpreteerd. Een veld kan aanwezig zijn, maar een andere betekenis hebben gekregen.
- Toegang: authenticatiemethode, machtigingen, verloop van inloggegevens en vereiste scopes.
- Gedrag: foutcodes, limieten voor verzoeken, volgorde van events, opnieuw proberen en idempotentie.
De matrix moet onderscheid maken tussen additieve en incompatibele wijzigingen. Een optioneel veld toevoegen heeft mogelijk geen gevolgen voor de consumer als die onbekende velden negeert; een verplicht veld hernoemen kan de werking wel verbreken. De beoordeling hangt af van het daadwerkelijke integratiecontract en van de manier waarop de clientcode is geschreven.
Afhankelijkheden en relevante combinaties inventariseren
Begin met het opsommen van elk extern systeem en het contactpunt: API, webhook, geïmporteerd bestand, queue, library of connector. Leg vast wie het onderhoudt, welke PHP-applicatie het gebruikt, welke gegevens worden uitgewisseld en welke bedrijfsprocessen ervan afhankelijk zijn. Neem omgevingen en configuraties op die het gedrag kunnen beïnvloeden, zoals regio, authenticatiemethode of datumformaat.
Identificeer vervolgens de waargenomen en officieel ondersteunde varianten: API-versies, platformversies, payloadschema's en toegangsconfiguraties. Ga er niet van uit dat elke theoretische combinatie relevant is. Geef prioriteit op basis van concrete signalen:
- Volume van het verkeer of van de betrokken bedrijfsprocessen.
- Aanwezigheid bij actieve klanten, regio's of installaties.
- Impact van een storing en de mogelijkheid om de bewerking te herstellen of opnieuw uit te voeren.
- Historie van wijzigingen en incidenten, en bekende verschillen tussen versies.
- Beschikbaarheid van een testomgeving of representatieve gegevens.
Als er veel combinaties zijn, hoef je ze niet allemaal te testen. Bepaal de testdekking op basis van risico: meest gebruikte versies, meest recente versies, ondersteuningsgrenzen en combinaties die verschillen in authenticatie of schema. Noteer welke combinaties niet zijn getest; stilte mag niet worden opgevat als bevestigde compatibiliteit.
Een bruikbare en uitvoerbare matrix opstellen
Een rij staat voor een verifieerbaar scenario, niet alleen voor een providernaam. De rij kan het systeem, de versie, de bewerking, het formaat, de authenticatie, de supportstatus, het validatieniveau, beperkingen, de verantwoordelijke en de datum van beoordeling bevatten. Voeg een verwijzing toe naar de geautomatiseerde test, fixture of het bewijs van validatie dat de status onderbouwt.
Gebruik ondubbelzinnige statussen. Bijvoorbeeld: ondersteund en getest, ondersteund met gedocumenteerde beperkingen, validatie in afwachting of niet langer ondersteund. Maak onderscheid tussen compatibiliteit die de provider aangeeft en compatibiliteit die je eigen team heeft gevalideerd. Een versie kan officieel compatibel zijn volgens de externe partij, zonder getest te zijn in jouw applicatie.
Definieer ook de grenzen: minimale en maximale versies, gedekte bewerkingen, niet-ondersteund gedrag en voorwaarden voor het activeren van de integratie. Wijs verantwoordelijken aan voor het bijwerken van de matrix en het goedkeuren van uitzonderingen. Zonder die verantwoordelijkheid raakt het document doorgaans verouderd, zelfs als de tests blijven draaien.
Prioritaire scenario's omzetten in tests
Tests moeten contracten en relevante resultaten controleren, niet alleen of een verzoek HTTP 200 oplevert. Valideer voor elk prioritair scenario de structuur, typen, verplichte velden, semantische regels en reacties op verwachte fouten. Neem waar van toepassing paginering, limieten, duplicaten, opnieuw proberen en verlopen authenticatie mee.
In een PHP-applicatie kunnen unit tests adapters en mappers controleren met fixtures onder versiebeheer. Contracttests controleren of verzoeken en antwoorden voldoen aan de verwachte afspraken. Integratietests testen de communicatie met een gecontroleerde omgeving van de provider, als die beschikbaar is. Elk niveau beantwoordt andere vragen: een fixture bewijst niet dat de externe service nog operationeel is, en een test tegen de service vervangt de deterministische testgevallen voor transformaties niet.
Bewaar representatieve en waar nodig geanonimiseerde fixtures. Vermijd tokens, onnodige persoonsgegevens of vertrouwelijke informatie. Als de provider schema's vaak wijzigt, kan een geautomatiseerde contractvergelijking verschillen signaleren; een menselijke beoordeling moet bepalen of die onschadelijk, incompatibel of zakelijk relevant zijn.
Incompatibele wijzigingen beheren zonder te laat te reageren
Stel signalen in om wijzigingen op te sporen: meldingen van de provider, nieuwe versies van documentatie, onverwachte antwoorden, validatiefouten en foutstatistieken per endpoint of versie. Leg de waargenomen versie of variant veilig vast in de logs, zonder inloggegevens of gevoelige gegevens bloot te leggen, zodat een incident aan een concreet scenario kan worden gekoppeld.
Classificeer een verschil voordat je de code aanpast. Een extra veld tolereren kan volstaan; voor een wijziging van het type is wellicht een expliciete conversie nodig; een semantische wijziging kan een productbeslissing vereisen. Houd de aanpassing op een duidelijke grens, zoals een client of adapter, en voorkom dat bijzonderheden van de provider zich door de hele applicatie verspreiden.
Als een update niet direct kan worden geactiveerd, definieer dan een overgang: tests met de nieuwe versie, een gecontroleerde uitrol, observatie van fouten en een procedure om de uitrol terug te draaien. Code uitrollen is niet hetzelfde als een nieuwe route activeren of de blootstelling eraan voor alle gebruikers activeren; als de architectuur dit toelaat, kan die blootstelling stapsgewijs worden uitgebreid. Behoud voor lopende bewerkingen compatibiliteit met reeds verstuurde berichten en voorkom dat niet-idempotente acties bij opnieuw proberen worden herhaald.
Varianten uitfaseren zonder processen te onderbreken
Om een variant niet langer te ondersteunen, zijn expliciete criteria nodig: einde van de ondersteuning door de provider, resterend gebruik, kosten van het onderhouden van tests, beveiligingsrisico's of de onmogelijkheid om het gedrag te garanderen. Meet vóór het uitfaseren het gebruik en breng de getroffen gebruikers in kaart. Een termijn afspreken, de wijziging communiceren en een migratieroute bieden, verkleint de kans op verrassingen.
Scheid het uitfaseren van een variant van het direct verwijderen van gegevens of openstaande processen. Controleer bij queues, synchronisaties of geplande taken of deze veilig kunnen worden afgerond, opnieuw uitgevoerd of gemigreerd. Registreer de afwijzing na de deadline duidelijk en waarneembaar; laat een stille degradatie een verouderde integratie niet in datacorruptie veranderen.
Checklist bij een wijziging van een afhankelijkheid
- Is de inventaris bijgewerkt met de versies, formaten, authenticatie en betrokken bewerkingen?
- Zijn de contracten vergeleken en wijzigingen in typen en semantiek beoordeeld?
- Zijn er fixtures en tests voor de prioritaire combinaties en foutgevallen?
- Zijn machtigingen, geheimen, persoonsgegevens en limieten voor verzoeken gecontroleerd?
- Zijn verantwoordelijken, criteria voor activering, monitoring en procedures voor terugdraaien vastgelegd?
- Zijn klanten of processen geïdentificeerd die moeten migreren voordat een variant wordt uitgefaseerd?
- Geeft de matrix weer wat is getest, wat nog openstaat en wanneer de matrix opnieuw moet worden beoordeeld?
Een compatibiliteitsmatrix voor software-integraties is nuttig wanneer deze verifieerbare beslissingen ondersteunt: wat wordt ondersteund, met welk bewijs, onder welke beperkingen en tot wanneer. Door de matrix samen met de tests en het wijzigingsproces bij te houden, kun je verrassingen beperken zonder te streven naar een uitputtende dekking die geen waarde toevoegt.
