Co sprawdzić przy ocenie definicji API?

Definicja API: czym jest

Definicja API to udokumentowany kontrakt opisujący, w jaki sposób klient powinien wywoływać API i jak API będzie odpowiadać. Zazwyczaj obejmuje trasy endpointów, formaty żądań/odpowiedzi (na przykład pola JSON), typy danych, parametry wymagane vs. opcjonalne, uwierzytelnianie i uprawnienia, limity zapytań, formaty błędów oraz wszelkie określone oczekiwania dotyczące czasu lub kolejności.

W kontekście zautomatyzowanego handlu definicja API ma znaczenie, ponieważ każdy kolejny krok—pobieranie danych, logika sygnałów, decyzje wykonawcze i raportowanie—zależy od tego, co API gwarantuje, a co jedynie „stara się” zapewnić. Kluczowym celem oceny jest zrozumienie, które części są stabilną mechaniką, a które mogą się zmieniać wraz z warunkami rynkowymi, obciążeniem systemu i polityką dostawcy.

Jak sprawdzić definicję API (obiektywna lista kontrolna)

1. Kompletność kontraktu

• Endpointy i metody są wyraźnie wymienione.
• Schematy żądań i odpowiedzi są zdefiniowane, w tym znaczenie pól i typy danych.
• Istnieją przykłady normalnych odpowiedzi oraz każdego udokumentowanego typu błędu.
• Wymagania dotyczące uwierzytelniania i autoryzacji są określone (na przykład, w jaki sposób dostarczane są poświadczenia i jaki dostęp jest dozwolony).

2. Szczegóły zachowania (część „jak to działa”)

• Potwierdź, czy API definiuje kolejność lub spójność między wywołaniami (na przykład, czy „najnowszy” jest powiązany ze znacznikiem czasu).
• Sprawdź, jak reprezentowane są znaczniki czasu (format, strefa czasowa i czy odzwierciedlają czas zdarzenia, czy czas przetwarzania).
• Zweryfikuj, jak działają paginacja, filtrowanie i limity, w tym maksymalne rozmiary stron i wartości domyślne.

3. Warunki zmienne vs. stabilna mechanika

• Oddziel elementy stabilne (schemat, reguły parametrów, udokumentowane kody błędów) od elementów zmiennych (opóźnienia, luki w danych, ruch rynkowy, ograniczanie przepustowości z powodu obciążenia).
• Traktuj wszelkie stwierdzenia o „czasie rzeczywistym” lub „streamingu” jako deklarację behawioralną, którą należy zweryfikować za pomocą testów lub przykładowych odpowiedzi, a nie jako stałą obietnicę.

4. Dowody i dokumentacja Poszukaj artefaktów implementacyjnych, które pozwolą Ci zweryfikować kontrakt:

• Dokumentacja zawierająca przykładowe ładunki i odpowiedzi błędów.
• Polityka wersjonowania opisująca, w jaki sposób wprowadzane są zmiany i jak długo stare wersje pozostają wspierane.
• Zasoby testowe, takie jak środowiska piaskownicy, endpointy testowe (mock) lub nagrane przykładowe wywołania.

5. Jasne stwierdzenia ograniczeń (czerwone flagi) Zidentyfikuj luki, w których dokumentacja milczy lub jest niejednoznaczna:

• Brakujące definicje krytycznych pól.
• Niejasna semantyka błędów (na przykład, czy błąd można ponowić).
• Brak opisu mechanizmu przeciążenia (backpressure), zachowania limitów zapytań lub tego, co dzieje się podczas częściowych awarii.

Dowód lub przykład: co oznacza „weryfikacja”

Praktycznym przykładem oceny opartej na dowodach jest uruchomienie skryptowych wywołań obejmujących:

• Żądanie „ścieżki szczęśliwej” i potwierdzenie, że pola odpowiedzi odpowiadają udokumentowanemu schematowi.
• Co najmniej jeden warunek brzegowy, taki jak nieprawidłowy parametr, który powinien wywołać udokumentowany błąd.
• Kontrolę opóźnienia/czasu poprzez pomiar czasu odpowiedzi (round-trip) i porównanie go z wszelkimi określonymi oczekiwaniami czasowymi.

Przykład założenia (określ je wprost): jeśli mierzysz czas odpowiedzi za pomocą własnego zegara systemowego, zakładasz, że Twój zegar jest w rozsądnym stopniu zsynchronizowany. Bez tego założenia porównania czasowe mogą być mylące.

Ograniczenia i tryby awarii, które należy uwzględnić

Oceń co najmniej jeden istotny tryb awarii:

• Luki w danych: API może zwracać niekompletną historię, brakujące zdarzenia lub opóźnione aktualizacje.
• Problemy z opóźnieniem i kolejnością: nawet jeśli istnieją znaczniki czasu, kolejność wywołań może nie odpowiadać kolejności zdarzeń.
• Ograniczanie zapytań lub ograniczanie przepustowości: nadmierne żądania mogą prowadzić do opóźnień lub strukturalnych błędów.
• Dryf schematu: wersje API mogą zmieniać pola, typy lub wymagane parametry.
• Awarie uwierzytelniania/uprawnień: tokeny mogą wygasać, a zakresy dostępu mogą się różnić w zależności od środowiska.

Historyczne zależności nie stanowią podstawy do przewidywania przyszłych wyników. Nawet jeśli przykładowe odpowiedzi wyglądają spójnie, przyszłe zachowanie może się zmienić, gdy dostawca zaktualizuje usługi lub gdy zmienią się obciążenie systemu i zmienność rynku. Wyniki różnią się również w zależności od kosztów, metody realizacji i jurysdykcji, dlatego traktuj definicję API jako opis kontraktu, a nie gwarancję wydajności.

Kryteria weryfikacji i kolejne pytania

Przed integracją zastosuj jasne „kryterium ukończenia”:

• Możesz przypisać każdy wymagany parametr i każde zwracane pole do udokumentowanego znaczenia.
• Możesz odtworzyć udokumentowane odpowiedzi sukcesu i błędu w środowisku testowym.
• Masz udokumentowane założenia dotyczące czasu, ponawiania prób i kompletności danych.
• Masz plan obsługi limitów zapytań, nieznanych pól i zmian wersji.

Kolejne pytania, które należy zadać podczas oceny:

• Jaki dokładnie jest udokumentowany model spójności API dla znaczników czasu i kolejności? - Które błędy można ponowić i jakie wytyczne dotyczące czasu oczekiwania (backoff) są podane?