Antwoord.

Historisch gezien was de beschrijving van de interfaces tussen systemen een taak voor architecten en integratoren, die vaak bestond uit het uitwisselen van e-mails met datastructuren. In het tijdperk van SOA, en vooral microservices architectuur, is de rol van de systeemanalist in de formalisatie en ondersteuning van integratiecontracten aanzienlijk toegenomen.

Probleem

Onjuiste, onvolledige of verouderde beschrijvingen van API-interfaces leiden tot: incompatibiliteit van services, een toename van bugs, en de onmogelijkheid om wijzigingen door te voeren zonder het cascade-effect van systeemuitval. In multi-service projecten bereikt het aantal integratiepunten tientallen of honderden.

Oplossing

De systeemanalist past moderne praktijken toe:

formalisatie van contracten via tools zoals OpenAPI/Swagger voor REST, gRPC-protocol, WSDL/XSD voor SOAP;
beschrijving van typische oproepscenario's en foutensituaties;
ontwikkeling van gebeurtenismodellen (event-driven model) voor realtime uitwisseling;
onderhouden van actuele documentatie en autogeneratie van contracten;
afstemming van wijzigingen met de eigenaren van alle getroffen services.

Een belangrijk element is het bijhouden van correcte versiebepaling en traceability van contractwijzigingen, evenals de integratie van testcases voor validatie van interacties.

Kernkenmerken:

Gebruik van machine-leesbare standaarden (OpenAPI/YAML).
Overweging van alle gebruiks- en foutenscenario's.
Gereguleerde communicatie tussen teams van verschillende services.

Vragen met een valstrik.

Moet de analist API-vereisten alleen verzamelen van de opdrachtgever en interne ontwikkelaars?

Nee, het is belangrijk om alle geïntegreerde teams erbij te betrekken, rekening te houden met de eisen van externe partners, om hiaten of incompatibiliteit te vermijden.

Kan de API alleen gedocumenteerd worden in de fase van systeemoplevering?

Nee, de specificatie van de API wordt gevormd en goedgekeurd voordat de implementatie begint, anders wordt de achterwaartse compatibiliteit op elk niveau geschonden.

Is de OpenAPI-specificatie op zich voldoende documentatie voor alle uitwisselingsgevallen?

Nee, OpenAPI beschrijft structuren, maar de interactiescenario's (bijvoorbeeld de volgorde van aanroepen, de volgorde van gebeurtenissen, zakelijke fouten) moet de analist in gebruikersdocumentatie uiteenzetten.

Typische fouten en anti-patronen

Verouderde documentatie of "menselijke" beschrijvingen geven in plaats van specificaties.
Geen foutafhandelingsscenario's en impliciete scenario's beschrijven.
Gebrek aan versiebeheer en wijzigingstracering.

Voorbeeld uit het leven

Negatief geval: Het logistieke systeem werd geïntegreerd met externe vervoerders. Het contract werd alleen "in woorden" beschreven. Na wijzigingen kwamen er massale integratiefouten en vertragingen.

Voordelen:

Minimale inspanning aan het begin.

Nadelen:

Massale storingen.
Spoedverbeteringen.
Negatieve reputatie.

Positief geval: De analist stelde een OpenAPI op met voorbeelden van fouten/succesvolle scenario's, stemde de versie af, en verzamelde feedback van alle teams.