Jak można zweryfikować informacje o definicji API?

Co definicja API oznacza w praktyce

Definicja API zwykle odnosi się do formalnej specyfikacji działania interfejsu API: dostępnych punktów końcowych (lub operacji), wymaganych danych wejściowych, opcjonalnych danych wejściowych, oczekiwanych danych wyjściowych, typów danych, reguł walidacji i formatów błędów. Może być zapisana jako dokument OpenAPI/Swagger, schemat JSON, wewnętrzna specyfikacja dla programistów lub czytelna dla człowieka dokumentacja.

Weryfikując informacje o definicji API, nie próbujesz potwierdzić, że dana idea jest „prawdziwa” w sensie ogólnym — sprawdzasz, czy udokumentowany kontrakt jest spójny, testowalny i powtarzalny dla danej wersji API.

Jak przebiega proces weryfikacji (hierarchia źródeł)

Użyj hierarchii źródeł zgodnej z tym, jak należy potwierdzać „stabilne mechanizmy”.

1. Podstawowe artefakty kontraktu (najbardziej stabilne)

   • Rzeczywiste dokumenty definicji API opublikowane przez dostawcę (na przykład plik OpenAPI).
   • Wszelkie schematy odczytywalne maszynowo dołączone do dokumentacji.
   • Udokumentowany identyfikator wersji i dziennik zmian.

2. Dokumentacja dostawcy (warstwa interpretacji)

   • Przewodniki opisujące, jak tworzyć żądania i interpretować odpowiedzi.
   • Sekcje dotyczące obsługi błędów oraz uwierzytelniania/autoryzacji, jeśli wpływają na strukturę żądań/odpowiedzi.

3. Zaobserwowane zachowanie na podstawie kontrolowanego testu (weryfikacja rzeczywistości)

   • Niewielki zestaw żądań w środowisku nieprodukcyjnym lub piaskownicy, jeśli jest dostępne.
   • Walidacja, czy pola, typy i ograniczenia odpowiedzi są zgodne z definicją.

W praktyce weryfikacja jest najsilniejsza, gdy można wykazać, że dokumentacja, schemat i odpowiedzi są zgodne dla tej samej wersji.

Dowody i powtarzalne kroki weryfikacji

Postępuj zgodnie z procesem krok po kroku, który można powtórzyć.

Krok 1: Ustal wersję i zakres

Zapisz wersję API oraz dokładny artefakt definicji, którego używasz (nazwa pliku, adres URL lub identyfikator zatwierdzenia). Załóż, że różne wersje mogą mieć różne nazwy pól, wymagane parametry i formaty błędów.

Krok 2: Porównaj strukturę z definicją

Dla każdego punktu końcowego, który Cię interesuje, zweryfikuj, czy:

• Lista wymaganych parametrów jest jednoznaczna.
• Parametry opcjonalne są rozróżnialne.
• Pola wyjściowe są udokumentowane z typami danych lub schematami.
• Odpowiedzi błędów mają udokumentowaną strukturę (na przykład kod błędu plus komunikat lub lista problemów z walidacją).

Krok 3: Utwórz minimalne przypadki testowe z jawnymi założeniami

Wybierz niewielki zestaw żądań obejmujący:

• Przypadek „ścieżki szczęśliwej” tylko z wymaganymi polami.
• Przypadek walidacji (celowo błędny typ lub brak wymaganego pola) w celu potwierdzenia zachowania przy błędach.

Załóż brak danych rynkowych w czasie rzeczywistym. Jeśli API wymaga parametrów, które zwykle zależą od stanu zewnętrznego (takich jak symbole lub identyfikatory), użyj wartości dostarczanych przez środowisko testowe lub potraktuj brakujące/nieprawidłowe wartości jako dane wejściowe testu, zamiast próbować przewidywać wyniki.

Krok 4: Porównaj odpowiedzi z definicją

Dla każdej odpowiedzi:

• Sprawdź, czy ładunek odpowiedzi zawiera opisane pola.
• Sprawdź, czy typy danych są zgodne z oczekiwaniami (ciąg znaków vs liczba, obiekt vs lista).
• Potwierdź, że błędy mają kształt zgodny z dokumentacją, gdy żądania są nieprawidłowe.

Jeśli definicja mówi, że pole jest opcjonalne, ale nigdy nie pojawia się w odpowiedziach, jest to rozbieżność do odnotowania. I odwrotnie, jeśli dodatkowe pola pojawiają się konsekwentnie, odnotuj je jako „zaobserwowane, ale nieudokumentowane”, co może wskazywać na lukę w dokumentacji.

Krok 5: Śledź tryby awarii, nie tylko wyniki

Co najmniej jedno istotne ograniczenie powinno być częścią weryfikacji:

• Dryf wersji: dokumentacja może pozostawać w tyle za zachowaniem po aktualizacjach.
• Niespójne schematy: pola mogą być udokumentowane, ale brakować ich lub mieć zmienione nazwy.
• Różnice w walidacji: formaty błędów mogą się różnić w zależności od punktu końcowego.
• Różnice środowiskowe: zachowanie w piaskownicy i w środowisku produkcyjnym może się różnić.

Traktuj je jako wyniki weryfikacji, a nie jako oznaki poprawności.

Ograniczenia i ryzyka, których należy się spodziewać

Nawet przy starannych kontrolach weryfikacja jest ograniczona przez niepewność i zmiany.

• Żaden pojedynczy test nie gwarantuje długoterminowej dokładności. Definicja może być poprawna dzisiaj, ale nadal stać się nieaktualna po aktualizacjach dostawcy.
• Zachowanie może się różnić w zależności od kontekstu. Koszty, warunki wykonania, uprawnienia i awarie sieci mogą zmieniać odpowiedzi, które widzisz, nawet gdy kontrakt jest stabilny.
• Zgodność w przeszłości nie gwarantuje zgodności w przyszłości. Jeśli odpowiedzi były wcześniej zgodne, nie gwarantuje to zgodności po zmianie wersji.

Ze względu na te ograniczenia powiąż weryfikację z konkretną wersją i konkretnym środowiskiem testowym.

Lista kontrolna weryfikacji i kolejne pytanie do rozstrzygnięcia

Skorzystaj z tej listy kontrolnej, aby weryfikacja była powtarzalna:

• Zapisano wersję zarówno dla dokumentacji, jak i testów. - Wyliczono punkty końcowe i pola na podstawie definicji. - Utworzono minimalne żądania „ścieżki szczęśliwej” i „błędu walidacji” z jawnymi założeniami.