Odpowiedź.

Historycznie opis interfejsów między systemami był zajęciem architektów i integratorów, często sprowadzającym się do wymiany e-maili ze strukturą danych. W epoce SOA, a tym bardziej w architekturze mikroserwisowej, rola analityka systemowego w formalizacji i wsparciu kontraktów integracyjnych znacznie wzrosła.

Problem

Błędny, niekompletny lub przestarzały opis interfejsów API staje się przyczyną: niekompatybilności usług, wzrostu liczby błędów, niemożności wprowadzenia zmian bez kaskadowego naruszenia działania całego systemu. W projektach wielousługowych liczba punktów integracji osiąga dziesiątki i setki.

Rozwiązanie

Analityk systemowy stosuje nowoczesne praktyki:

formalizacja kontraktów za pomocą narzędzi typu OpenAPI/Swagger dla REST, protokołów gRPC, WSDL/XSD dla SOAP;
opis typowych scenariuszy wywołania i sytuacji błędnych;
rozwój modeli zdarzeń (event-driven model) dla wymiany w czasie rzeczywistym;
prowadzenie aktualnej dokumentacji i autogeneracja kontraktów;
uzgadnianie zmian z właścicielami wszystkich zaangażowanych usług.

Ważnym elementem jest prowadzenie właściwej wersjonowania i śledzenia zmian kontraktów, a także integracja przypadków testowych w celu walidacji interakcji.

Kluczowe cechy:

Zastosowanie standardów maszynowo czytelnych (OpenAPI/YAML).
Ujęcie wszystkich scenariuszy użycia i błędów.
Regulowana komunikacja między zespołami różnych usług.

Pytania pułapki.

Czy analityk powinien zbierać wymagania dotyczące API tylko od zamawiającego i wewnętrznych programistów?

Nie, ważne jest zaangażowanie wszystkich zintegrowanych zespołów, uwzględnienie wymagań zewnętrznych partnerów, aby uniknąć luk lub niekompatybilności.

Czy można dokumentować API tylko na etapie oddania systemu?

Nie, specyfikacja API jest tworzona i uzgadniana jeszcze przed realizacją, w przeciwnym razie wsteczna zgodność zostanie naruszona na każdym etapie.

Czy specyfikacja OpenAPI sama w sobie jest wystarczającą dokumentacją dla wszystkich przypadków wymiany?

Nie, OpenAPI opisuje struktury, ale analityk jest zobowiązany do opisania scenariuszy interakcji (np. kolejność wywołań, sekwencja zdarzeń, błędy biznesowe) w dokumentacji użytkownika.

Typowe błędy i antywzorce

Przekazywanie przestarzałych dokumentów lub "ludzkich" opisów zamiast specyfikacji.
Nieopisanie obsługi błędów, niejawne scenariusze.
Brak kontroli wersji i śledzenia zmian.

Przykład z życia

Negatywny przypadek: System logistyki zintegrował się z zewnętrznymi przewoźnikami. Kontrakt opisano tylko "słownie". Po wprowadzeniu zmian wystąpiły masowe awarie integracji, opóźnienia.

Zalety:

Minimalne koszty pracy na początku

Wady:

Masowe awarie
Pilne poprawki
Negatywna reputacja

Pozytywny przypadek: Analityk sporządził OpenAPI z przykładami błędów/sukcesów, uzgodnił wersjonowanie, zebrał opinie od wszystkich zespołów.