Idempotentność

Interfejs API Platformy obsługuje funkcję kluczy idempotencji (x-idempotency-key) w celu bezpiecznego ponownego przesłania żądań bez przypadkowego dwukrotnego wykonania tej samej operacji. Jest to przydatne np. gdy połączenie API zostanie przerwane podczas przesyłania i nie otrzymasz odpowiedzi.

Na przykład, jeśli żądanie do API Platformy o utworzenia Wirtualnej Maszynie nie odpowiada z powodu błędu połączenia sieciowego, programista nie otrzyma odpowiedzi. Może to utrudniać określenie, czy żądanie się powiodło, czy nie, co może prowadzić do wielokrotnych prób w celu zapewnienia pomyślnego zakończenia operacji. Jeśli jednak pierwotne żądanie i kolejne próby nie zawierały klucza idempotencji zakończyły się sukcesem, operacja jest wykonywana wielokrotnie. Oznacza to, że można stworzyć więcej zasobów niż zamierzone.

Aby zapobiec takim sytuacjom można wraz z żądaniem przesłać klucz idempotencji. Aby to zrobić należy w nagłówku żądaniu HTTP przesłać dodatkowy parametr x-idempotency-key.

Przesłanie klucza idempotencji skutkuje zapisaniem pierwszego wynikowego kodu statusu i odpowiedzi wykonanej dla danej wartości, niezależnie od tego, czy zakończyło się ono sukcesem czy porażką. Kolejne żądania z tym samym kluczem zwracają ten sam wynik, łącznie z 500 błędami, niezależnie od ilości powtórzeń żądania. Parametr idempotencji zapewnia, że żądanie API zostanie ukończone nie więcej niż jeden raz. W przypadku idempotencjalnego żądania, jeśli pierwotne żądanie zakończy się sukcesem, wszystkie kolejne próby zwrócą wynik z pierwotnego udanego żądania i nie będą miały żadnego dodatkowych skutków.

Wartość parametru x-idempotency-key jest unikalną wartością w postaci ciągu znaków alfanumerycznego generowaną przez klienta, w której wielkość liter ma znaczenia i która jest używana przez serwer do rozpoznawania kolejnych prób tożsamego żądania. Nie jest wymagany ścisły format, ani sposób tworzenia unikalnych kluczy. Rekomendujemy użycie UUID v4 (opens new window), lub innego losowego ciągu znaków z wystarczającą ilością entropii, aby uniknąć kolizji.

Klucze mogą być zapomniane przez Platformę API po upływie co najmniej 24 godzin, a nowe operacja jest wykonywana, jeśli klucz zostanie ponownie użyty po jego zapomnieniu.

Wyniki odpowiedzi są zapisywane tylko wtedy, gdy punkt końcowy API rozpoczął wykonywanie. Jeśli przesłane parametry nie zostały zaakceptowane nie jest zapisywany żaden wynik, ponieważ żaden punkt końcowy API nie rozpoczął wykonywania. Powtórne wykonywanie tych żądań jest bezpieczne.

Wszystkie żądania POST, PUT, PATCH i DELETE akceptują klucze idempotencji. Wysyłanie kluczy idempotencji w żądaniach GET nie ma żadnego skutku i powinno być unikane, ponieważ żądania te są z definicji idempotencjalne.

Zalecenia dotyczące powtórzenia żądań z kluczem idempotencji

W poniższej tabeli przedstawiono niektóre typowe odpowiedzi, które można uzyskać w przypadku żądań z kluczem idempotencji do API Platformy, oraz zalecenia dotyczące ponownych prób.

Klasa odpowiedzi	Zachowanie
Klasa 2xx	Klasa 2xx (Successful) kodu statusu wskazuje, że żądanie zostało pomyślnie przyjęte, zrozumiane i zaakceptowany. Wszelkie kolejne próby żądania zwrócą wynik z pierwotnego pomyślnego żądania i nie mają dodatkowego efektu.
Klasa 4xx	Klasa 4xx (Client Error) kodu statusu wskazuje, że klient wydaje się, że się pomylił np. sformułował nieprawidłowe żądanie, przekazał niedopuszczalne parametry lub odwołał się do Zasobu nieistniejącego lub w niedopuszczalnym stanie. Żądana operacja nie została rozpoczęta. Jeśli żądanie dotyczy Zasobu, który jest w trakcie zmiany stanu, ponawianie żądania z uwzględnieniem strategii "back-off" może się powieść.
Klasa 5xx	Klasa 5xx (Server Error) kodu statusu wskazuje, że serwer jest świadomy, że popełnił błąd lub nie jest w stanie wykonać danego żądana metoda. Błąd jest najprawdopodobnie spowodowany problemem po stronie Platformy HyperOne i na ogół jest przejściowy. Rekomendujemy powtórzenie żądanie z odpowiednią strategią "back-off".

Strategia "back-off" oznacza, że gdy wystąpi błąd, aplikacja powinna odczekać interwał ponowienia i ponowić żądanie przed wydaniem kolejnego żądania. Rekomendujemy po pierwszym błędzie zachować minimalny interwał ponowienia wynoszący 1 sekundę, a dla każdego kolejnego błędu interwał powinien wzrastać wykładniczo do 32 sekund.