UML uzupełnia kontrakt API#
UML może wyjaśniać, kto korzysta z API, jak komponenty zależą od interfejsów i jak wygląda istotny scenariusz komunikacji. Diagramy pomagają opisać kontekst oraz zachowanie, ale nie zastępują kompletnej specyfikacji endpointów, schematów wiadomości, błędów, autoryzacji i wersjonowania.
Diagram pokazuje jeden przebieg sukcesu: klient wysyła żądanie, usługa sprawdza dostępność i zwraca identyfikator. Nie określa kompletnego formatu JSON, nagłówków, kodowania, schematów błędów ani zachowania przy timeoutcie. Te informacje powinny należeć do kontraktu API.
Diagramy przydatne w API#
Diagram komponentów może pokazać, który komponent udostępnia interfejs, kto z niego korzysta i gdzie przebiega granica usługi. Diagram sekwencji wyjaśnia kolejność żądań, odpowiedzi, błędów i komunikatów asynchronicznych. Diagram klas może opisać model domenowy lub struktury danych, jeśli nie pomylisz go ze schematem serializacji.
Diagram aktywności może pokazać walidację, decyzje i warianty obsługi żądania, a maszyna stanów — dozwolone przejścia zasobu, np. zamówienia lub subskrypcji. Każdy widok powinien odpowiadać na konkretne pytanie i wskazywać, czy opisuje zachowanie klienta, serwera czy całej integracji.
Co powinien określać kontrakt API#
W zależności od stylu interfejsu i wymagań kontrakt może zawierać:
- operacje lub zasoby, metody, ścieżki i parametry;
- typy, formaty, ograniczenia i schematy żądań oraz odpowiedzi;
- kody wyników, błędy, walidację i semantykę ponowień;
- uwierzytelnienie, autoryzację i poufność danych;
- limity, timeouty, paginację, idempotencję i kolejność zdarzeń;
- zasady wersjonowania, kompatybilności i wycofywania;
- przykłady, wymagane nagłówki i zachowanie przy wartościach brzegowych.
Nie każda integracja wymaga wszystkich punktów, a ich znaczenie zależy od protokołu i użytkowników API. UML nie definiuje tych szczegółów automatycznie. Użyj specyfikacji odpowiedniej dla interfejsu i traktuj diagram jako kontekst lub uzupełnienie.
Diagram klas a format komunikatu#
Klasa domenowa Zamowienie może mieć relacje i operacje, które nie odpowiadają jeden do jednego polom w JSON lub XML. API może ukrywać wewnętrzne klasy, agregować kilka obiektów w jeden dokument, używać identyfikatorów zamiast zagnieżdżonych struktur albo stosować różne reprezentacje dla odczytu i zapisu.
Jeśli diagram modeluje dokładnie schemat wiadomości, nazwij ten zakres i pokaż opcjonalność, wymagane pola, enumeracje oraz ograniczenia. Nie wyciągaj ze zwykłej asocjacji wniosku o kształcie payloadu. Utrzymuj jedno źródło prawdy i określ, czy schemat jest generowany z modelu, czy model odzwierciedla niezależną specyfikację.
Scenariusze błędów i asynchroniczność#
Interakcja API często ma kilka rezultatów: sukces, walidację odrzuconą, brak autoryzacji, konflikt stanu, niedostępność zależności lub timeout. Diagram sekwencji może pokazać najważniejsze alternatywy, a diagram aktywności warunki wyboru. Oznacz, które ścieżki pominięto.
W API asynchronicznym żądanie może jedynie zainicjować pracę, która kończy się później. Pokaż akceptację żądania, korelację, callback lub zdarzenie końcowe, jeśli mają znaczenie dla odbiorcy. Nie przedstawiaj odpowiedzi 202 ani potwierdzenia kolejki jako dowodu, że zadanie biznesowe zakończyło się sukcesem.
Wersje i źródło prawdy#
Ustal, co jest nadrzędne: specyfikacja interfejsu, kod, diagram czy kontrakt uzgadniany w repozytorium. Diagramy ręczne mogą szybko się dezaktualizować, szczególnie jeśli powielają wszystkie operacje i schematy. Trzymaj źródła obok dokumentacji, jeśli to możliwe, i uruchamiaj walidację w przeglądzie zmian.
Zmiana publicznego zachowania powinna uruchomić przegląd diagramów scenariuszy i zależnych dokumentów. Zmiana wewnętrznej implementacji nie musi zmieniać diagramu kontraktu. Zaznacz, czy widok opisuje wersję interfejsu, stan bieżący czy planowaną zmianę.
Dostępność dla odbiorców#
Klienci API mogą nie znać UML. Używaj prostych nazw, podpisuj przykłady i nie opieraj zrozumienia na nieobjaśnionych stereotypach. Dla publicznego interfejsu zapewnij specyfikację maszynową i przykłady użycia; diagram może ułatwić onboarding oraz rozmowę o przepływach.
Diagram nie powinien zawierać poufnych tokenów, adresów środowisk, danych osobowych ani szczegółów infrastruktury, które nie są przeznaczone dla jego odbiorców. Przed publikacją sprawdź zakres i pochodzenie przykładów.
Typowe błędy#
- Diagram uznany za dokumentację endpointów. Uzupełnij go formalnym kontraktem i schematami.
- Model domeny utożsamiony z payloadem. Mapowanie może być inne i wymaga jawnego określenia.
- Pokazany tylko sukces. Dodaj ważne błędy lub zaznacz ograniczenie scenariusza.
- Potwierdzenie techniczne uznane za wynik biznesowy. Rozróżnij przyjęcie zlecenia od jego zakończenia.
- Wszystkie operacje przepisane do diagramu. Utrzymuj diagram na poziomie scenariusza, a pełne API w specyfikacji.
- Brak źródła prawdy. Ustal, który artefakt opisuje kontrakt i jak wersje są synchronizowane.
- UML uznany za format interoperacyjny API. Użyj formatu specyfikacji właściwego dla protokołu.
Podsumowanie#
UML pomaga pokazać kontekst, zależności i scenariusze API, ale nie zastępuje schematów i reguł kontraktu. Łącz diagramy komponentów, sekwencji, klas lub aktywności z formalną specyfikacją interfejsu. Utrzymuj jasne źródło prawdy i uwzględniaj istotne błędy, wersje oraz zachowanie asynchroniczne.