Wyobraź sobie, że strona do składania zamówień wysyła nowe zamówienie do systemu operacyjnej obsługi firmy. System je zapisuje, lecz potwierdzenie nie dociera do strony. Czy strona powinna spróbować ponownie? Czy może to utworzyć drugie zamówienie? Ten przykład pokazuje, dlaczego kontrakt API ma znaczenie dla działania firmy. Opisuje oczekiwane zachowanie obu stron, także w sytuacjach, których udana demonstracja może nigdy nie ujawnić.
Na tej stronie
Zacznij od procesu biznesowego i odpowiedzialności za dane
Zmapuj jedną interakcję od działania użytkownika do potwierdzonego wyniku. W przykładzie zamówienia ustal, kto tworzy jego numer, który system decyduje o przyjęciu i gdzie klient sprawdza status. Rozróżnij odebranie żądania od przyjęcia zamówienia — mogą to być różne zdarzenia. Zdecyduj też, który system może zmieniać każdą informację. Jeżeli oba systemy mogą edytować adres dostawy, kontrakt potrzebuje reguły obsługi aktualizacji, zamiast zakładać, że ostatnio wyświetlony ekran zawiera wartość nadrzędną.
- Wskaż odpowiedzialność za informacje o zamówieniu, kliencie i statusie.
- Określ, jaki wynik użytkownik musi zobaczyć od razu.
- Zidentyfikuj późniejsze aktualizacje, które system odbierający musi wysłać.
Konkretnie zdefiniuj pola
Dla każdego komunikatu udokumentuj wymagane informacje, dopuszczalne wartości i znaczenie braku danych. Cena wymaga waluty i jednoznacznej interpretacji, a znacznik czasu — uzgodnionej konwencji stref czasowych. Omów te reguły na jednym realistycznym zamówieniu przykładowym. Zapytaj, czy „anulowane” opisuje całe zamówienie, czy pojedynczą pozycję, oraz czy pusty adres oznacza nieznany, czy celowo usunięty. Opisz, które rekordy każdy podmiot wywołujący API może odczytywać lub zmieniać. Te decyzje wpływają zarówno na specyfikację, jak i korzystanie z aplikacji — samo dopasowanie nazw pól ich nie rozstrzyga.
Określ obsługę ponawianych żądań i użytecznych błędów
Dla przykładowego zamówienia proponowana reguła mogłaby brzmieć: w uzgodnionym okresie przechowywania ponowne wysłanie tego samego identyfikatora żądania z identycznymi danymi zwraca istniejący numer zamówienia. Użycie tego identyfikatora z innymi danymi powoduje konflikt, który wywołujący musi rozwiązać. Jawnie zdefiniuj zakres identyfikatora i okres jego przechowywania. Następnie odróżnij błędy wymagające poprawienia od przejściowych awarii. Samo przekroczenie limitu czasu nie przesądza, czy zamówienie zostało zapisane, dlatego wywołujący potrzebuje sposobu sprawdzenia wyniku przed podjęciem kolejnego kroku.
- Brak adresu dostawy: zwróć wyjaśnienie dotyczące pola; przed ponownym wysłaniem popraw żądanie.
- Niepewny wynik: wyszukaj identyfikator żądania i uzgodnij jego zapisany stan.
- Przejściowa awaria usługi: stosuj uzgodnioną politykę ponowień; nie twórz nowej tożsamości zamówienia przy każdej próbie.
Uzgodnij sposób testowania i zmiany kontraktu
Poproś oba zespoły o przejście przez poprawne zamówienie, ponowione żądanie, nieprawidłowy adres i przerwane potwierdzenie. Sprawdź, czy w każdym przypadku oczekują tego samego wyniku. Przechowuj te przykłady razem ze specyfikacją i korzystaj z nich przy zmianach integracji. Wskaż osoby odpowiedzialne za zatwierdzanie zmian, informowanie połączonych zespołów i analizę incydentów. Przekazanie powinno wyjaśniać, jak wsparcie może prześledzić żądanie bez ujawniania niepotrzebnych danych klientów oraz jak niezgodna wstecznie zmiana zostanie wprowadzona u obecnych odbiorców API.