Idempotencja API: jak uniknąć podwójnego wykonania po ponowieniu żądania

Wyobraź sobie zamówienie wysłane z portalu do systemu magazynowego. Serwer przyjął żądanie i utworzył dokument, ale odpowiedź nie dotarła do portalu. Pracownik nadal widzi komunikat o oczekiwaniu. Po chwili naciska przycisk ponownie, bo chce wiedzieć, czy zlecenie istnieje. Bez odpowiednich zabezpieczeń system może utworzyć drugi dokument, choć intencja była jedna. To problem z rozpoznaniem operacji, a nie z cierpliwością pracownika.

Idempotencja oznacza tutaj taką właściwość operacji, przy której ponowienie tego samego zamiaru nie wywołuje kolejnego, niezamierzonego skutku. Brzmi technicznie, ale dotyczy spraw bardzo konkretnych: drugiego zamówienia, powtórnej rezerwacji lub kolejnej wiadomości do klienta. Dobrze zaprojektowana integracja pozwala ponawiać próbę i jednocześnie sprawdza, czy dana sprawa nie została już obsłużona.

Dlaczego brak odpowiedzi nie jest odpowiedzią

W wymianie danych uczestniczą co najmniej dwie strony, a po drodze może być jeszcze bramka, kolejka lub system zewnętrzny. Każda z nich ma swój czas działania. Połączenie może zostać przerwane przed przekazaniem żądania, podczas pracy serwera albo już po zapisaniu wyniku. Z perspektywy osoby, która wysłała żądanie, wszystkie trzy sytuacje mogą wyglądać podobnie: odpowiedź nie przyszła w ustalonym czasie.

Timeout mówi więc, że skończył się czas oczekiwania. Sam w sobie nie potwierdza, że druga strona nic nie zrobiła. To rozróżnienie powinno pojawić się w projekcie już przy omawianiu integracji systemów i odpowiedzialności za dane. Jeżeli nadawca od razu wyśle nową operację, może podwoić skutek. Jeżeli nigdy nie spróbuje ponownie, sprawa naprawdę niewykonana zostanie bez obsługi.

Niepewność może powstać także bez świadomego ponowienia przez pracownika. Klient API może mieć automatyczne ponawianie, system kolejkowy może ponownie dostarczyć wiadomość, a dostawca może wysłać webhook jeszcze raz, kiedy nie otrzyma potwierdzenia. Dlatego dobrze zinwentaryzować wszystkie miejsca, które mogą uruchomić tę samą czynność. Osobno opisujemy API i webhooki w automatyzacji, wraz z różnicą między odbiorem wiadomości a wykonaniem zadania.

Nadaj jednemu zamiarowi jeden identyfikator

Klucz idempotencji to identyfikator przypisany do konkretnego zamiaru, na przykład do jednej prośby o utworzenie rezerwacji. Nadawca tworzy go przed pierwszą próbą i zachowuje również wtedy, gdy musi ponowić żądanie. Odbiorca sprawdza, czy zna już ten klucz. Jeśli operacja zakończyła się wcześniej, może zwrócić zapisany wynik zamiast tworzyć nowy dokument. Dokładne zachowanie zależy jednak od umowy danego API i sposobu obsługi błędów.

W praktyce identyfikator powinien być wystarczająco unikalny, a jego zakres zrozumiały dla obu stron. Nie należy wkładać do niego adresu e-mail, numeru dokumentu ani innych danych, które mogą pojawić się potem w logach. Można użyć losowego identyfikatora i powiązać go we własnym systemie z numerem sprawy. Dzięki temu osoba wyjaśniająca problem odnajdzie właściwy zapis, ale sam klucz nie będzie zdradzał treści sprawy.

Ważne jest również, żeby system nie generował nowego klucza dla każdego technicznego ponowienia tej samej operacji. W takim układzie odbiorca zobaczy serię różnych zamiarów i nie będzie miał podstaw, żeby je połączyć. Z kolei dwa rzeczywiście odrębne zamówienia potrzebują odrębnych identyfikatorów, nawet gdy dotyczą tego samego klienta i identycznych produktów. Podobieństwo treści nie jest automatycznie dowodem duplikatu.

Gdzie kończy się jedna operacja

Zanim wybierzesz pole w nagłówku żądania, ustal granicę operacji biznesowej. Czy jedną operacją jest dodanie pozycji do koszyka, utworzenie zamówienia, rezerwacja stanu magazynowego czy pobranie płatności? Każda z tych czynności może mieć własny rezultat i osobne ponowienia. Jeden identyfikator obejmujący cały proces bywa wygodny do śledzenia sprawy, ale nie zawsze wystarcza do bezpiecznego sterowania każdym krokiem.

Załóżmy, że zamówienie składa się z zapisania dokumentu i wysłania powiadomienia. Dokument może zostać utworzony poprawnie, a wiadomość może nie wyjść. Jeżeli system uzna cały proces za zakończony bez rozróżnienia obu rezultatów, ponowienie nie naprawi brakującego powiadomienia. Jeżeli potraktuje całość jako zupełnie nową sprawę, może ponownie zapisać dokument. Projekt powinien zatem przewidzieć stan poszczególnych kroków i sposób ich sprawdzenia.

Podobnie działa sytuacja odwrotna: powiadomienie wyszło, ale potwierdzenie wysyłki nie dotarło. To, czy można bezpiecznie ponowić wysyłkę, zależy od możliwości dostawcy i od własnego rejestru. Nie każdy zewnętrzny system oferuje identyczny mechanizm. Zanim obiecamy brak powtórzeń, sprawdźmy więc kontrakt każdego połączenia i określmy, co można potwierdzić, a co trzeba skierować do wyjaśnienia.

Nie zapominaj o operacjach zlecanych partiami. Jeśli użytkownik wybierze wiele rekordów, system musi wiedzieć, czy ponowienie dotyczy całego zestawu, czy tylko pozycji bez potwierdzenia. Warto zapisać wynik dla każdej pozycji i pokazać, które wymagają wyjaśnienia. Inaczej częściowo wykonana paczka może wyglądać jak jeden ogólny błąd, a kolejna próba ponownie uruchomi elementy już zakończone. Samo rozpoznanie ponowionego żądania nie rozstrzyga, która wartość jest prawidłowa. Tę osobną kwestię omawiamy w tekście o konfliktach danych między systemami.

Ten sam klucz i inne dane to sygnał konfliktu

Osoba może poprawić adres dostawy po pierwszej próbie. Czy to nadal ponowienie poprzedniego żądania, czy już nowa zmiana zamówienia? Odpowiedź musi wynikać z procesu. Dobrym zabezpieczeniem jest porównanie danych ponowienia z danymi pierwotnej operacji. Jeśli klucz jest taki sam, ale istotne parametry się zmieniły, system nie powinien po cichu zwracać starego wyniku tak, jakby odpowiadał nowym danym.

Przy konflikcie potrzebny jest czytelny komunikat: poprzednia operacja użyła tego identyfikatora z innymi danymi, a bieżąca próba wymaga nowej decyzji. Klient API musi wiedzieć, czy utworzyć osobną operację, sprawdzić wynik poprzedniej, czy przekazać sprawę człowiekowi. To także miejsce na ustalenie, które pola są istotne dla porównania. Inaczej zmiana technicznego znacznika czasu może błędnie wyglądać jak zmiana samego zamówienia.

Warto pokazać te zasady w dokumentacji integracji i na przykładach. Osoba wdrażająca drugą stronę musi wiedzieć, jak długo zachować identyfikator, jakie dane wysłać przy ponowieniu i jak odczytać wynik wcześniejszej próby. Bez tego nawet poprawny mechanizm po stronie serwera nie zapewni przewidywalnego działania całego procesu.

Rejestr wyniku wymaga osobnych ustaleń o przechowywaniu. Określ, kto może go odczytać, kiedy wygasa i jak wyjaśnić sprawę po wygaśnięciu danych. Nie musi zawierać całego dokumentu ani pełnej odpowiedzi z danymi osobowymi. Czasem wystarczy identyfikator rezultatu, stan i kontrolowany odnośnik do systemu, który jest właścicielem szczegółów. Zakres zapisu powinien umożliwić wyjaśnienie błędu bez tworzenia drugiej, niepotrzebnej kopii danych.

Sprawdź reguły konkretnego dostawcy

Nie istnieje jedna uniwersalna interpretacja klucza idempotencji dla wszystkich usług. Dokumentacja Stripe opisuje na przykład odmienne zachowanie ponowień w API v1 i v2. W API v1 zachowany może być również wynik pierwszego wywołania z błędem serwera po rozpoczęciu wykonania. W API v2 opisano inne podejście do częściowo nieudanych operacji. To dobry powód, żeby czytać dokumentację dokładnie dla używanej wersji, zamiast przenosić zasady z innej integracji.

W tej samej dokumentacji Stripe wskazuje, że dla API v1 klucze mogą zostać usunięte po co najmniej 24 godzinach. Ponowne użycie usuniętego klucza może wtedy uruchomić nowe żądanie. Nie oznacza to, że każda usługa ma taki sam okres przechowywania. Przy projektowaniu procesu trzeba ustalić, jak długo pracownicy lub automaty mogą wracać do sprawy i co zrobić, gdy okres rozpoznawania klucza po stronie dostawcy już minął.

Osobną kwestią jest znaczenie metod HTTP. Według dokumentacji MDN metody PUT i DELETE mają idempotentną semantykę, natomiast POST i PATCH nie dają takiej gwarancji. Nie należy jednak wyciągać z samej nazwy metody wniosku, że cały proces biznesowy jest bezpieczny przy dowolnym ponowieniu. Powiadomienia, integracje poboczne i zachowanie konkretnego serwera trzeba sprawdzić osobno.

Przed wdrożeniem rozdziel też odpowiedzialność za decyzję o ponowieniu. Aplikacja może automatycznie obsłużyć krótką przerwę w połączeniu, ale powtarzające się konflikty lub brak potwierdzenia po dłuższym czasie mogą wymagać ręcznej weryfikacji. Ustal limit prób, informację dla operatora oraz sposób zatrzymania procesu. Sama liczba prób nie rozstrzyga, czy ponowienie jest bezpieczne: musi jeszcze istnieć sposób rozpoznania pierwotnej operacji.

Przetestuj ponowienie, zanim zrobi to użytkownik

Test zwykłej, prawidłowej odpowiedzi nie wystarcza. W środowisku testowym przeprowadź próbę, w której odbiorca zapisuje operację, a nadawca nie dostaje odpowiedzi. Następnie ponów żądanie z tym samym kluczem i sprawdź zarówno odpowiedź API, jak i liczbę rzeczywistych dokumentów. Potem sprawdź wariant, w którym pierwsza próba nie rozpoczęła wykonania. W obu przypadkach oczekiwany rezultat powinien być opisany przed uruchomieniem testu.

Dodaj próby równoczesne: dwie identyczne wiadomości docierają niemal jednocześnie. Samo sprawdzenie w aplikacji, że klucza jeszcze nie ma, może nie wystarczyć, jeśli obie próby wykonają je przed zapisem wyniku. Potrzebne jest rozwiązanie dopasowane do bazy danych i architektury, które rozstrzygnie taki wyścig. Sprawdź też, co widzi nadawca, kiedy pierwsza operacja nadal trwa, a druga pyta o ten sam klucz.

Następnie powtórz test z tym samym kluczem i zmienioną kwotą, po upływie ustalonego okresu przechowywania oraz po ponownym uruchomieniu usługi. Zobacz, czy da się odnaleźć poprzedni wynik bez dostępu do danych, których operator nie powinien oglądać. W monitorowaniu automatyzacji warto przewidzieć miejsce dla spraw, których stan pozostał niejednoznaczny, zamiast bez końca wysyłać te same komunikaty.

Co przekazać zespołowi projektowemu

Przygotuj opis jednej operacji, której nie wolno przypadkowo powielić. Zapisz jej początek, rezultat, system odbierający i osobę odpowiedzialną za wyjaśnienie niepewnego wyniku. Dodaj informację o dostępnej dokumentacji API oraz o tym, czy dostawca udostępnia środowisko testowe. Nie trzeba przesyłać haseł, kluczy produkcyjnych ani prawdziwych danych klientów, żeby rozpocząć rozmowę o zakresie.

Jeżeli wynik ma trafić do raportu, ustal także sposób identyfikowania dokumentu i zasady korekt. Inaczej zdublowana operacja może być później widoczna jako dwie prawidłowe pozycje w zestawieniu. O związku definicji i źródeł danych piszemy przy projektowaniu dashboardu zarządczego; o tym, co trzeba ustalić przed pracą z danymi, w tekście o porządkowaniu danych przed wdrożeniem AI.

Jeśli chcesz sprawdzić podobny przepływ w swojej firmie, opisz go przez formularz kontaktowy Archifutura. W briefie podaj, co jest wysyłane, dokąd trafia i jaki skutek powinien pojawić się tylko raz. Możemy wspólnie ustalić zakres integracji systemów, dostępne sposoby potwierdzenia wyniku oraz scenariusze, które trzeba przetestować przed uruchomieniem.

W odbiorze uwzględnij również ponowienie po zmianie wersji aplikacji. Nowa wersja nadal powinna rozpoznawać operacje rozpoczęte przez poprzednią, o ile mieszczą się one w uzgodnionym okresie obsługi. Zespół może to sprawdzić, rozpoczynając próbę przed aktualizacją, a kończąc ją po wdrożeniu. To scenariusz, który łatwo pominąć podczas testowania wyłącznie świeżej instalacji, choć w działającej firmie sprawy nie zamykają się na czas aktualizacji.