Zły endpoint API to wywołanie błędnego adresu usługi, skutkujące odpowiedzią o nieistniejącym zasobie.
Co oznacza wywołanie złego endpointu API
Zły endpoint API oznacza próbę połączenia z adresem, pod którym serwer nie udostępnia oczekiwanej operacji. Endpoint jest konkretnym punktem dostępu do usługi, zwykle określonym przez adres URL oraz metodę HTTP. Przykładowo aplikacja może korzystać z adresu https://api.example.com/v1/users, aby pobierać listę użytkowników, natomiast adres https://api.example.com/v1/user może nie istnieć, ponieważ dokumentacja przewiduje liczbę mnogą users. Różnica jednego znaku w ścieżce wystarcza, aby żądanie trafiło do innej trasy albo nie zostało dopasowane do żadnej.
Problem może dotyczyć również domeny, portu, prefiksu wersji, parametrów ścieżki lub końcowego ukośnika. Serwer może oczekiwać ścieżki /api/v2/orders/123, podczas gdy klient wywołuje /api/orders/123 albo przekazuje identyfikator w parametrze zapytania jako /api/orders?id=123. Te adresy nie są automatycznie równoważne. O tym, który z nich działa, decyduje implementacja konkretnego API oraz konfiguracja routingu po stronie serwera.
Jak rozpoznać błąd na podstawie odpowiedzi HTTP
Najczęstszą odpowiedzią na nieistniejący adres zasobu jest status HTTP 404 Not Found. Oznacza on, że serwer nie znalazł bieżącej reprezentacji zasobu albo nie ujawnił jej pod podanym adresem. Sam status 404 nie zawsze dowodzi, że domena jest niedostępna. Połączenie z serwerem mogło zostać nawiązane prawidłowo, a błąd może występować wyłącznie w części ścieżki URL. Dlatego należy sprawdzić pełny adres, metodę, nagłówki oraz treść odpowiedzi.
Status 405 Method Not Allowed wskazuje inną sytuację: ścieżka może istnieć, ale użyto niewłaściwej metody HTTP. Na przykład API może zezwalać na GET /api/tickets/15, lecz odrzucać POST /api/tickets/15. W odpowiedzi 405 serwer powinien przekazać nagłówek Allow z metodami obsługiwanymi dla danego zasobu. Status 400 Bad Request częściej oznacza niepoprawną składnię lub dane żądania, a 401 Unauthorized i 403 Forbidden dotyczą uwierzytelnienia albo uprawnień, nie samego istnienia endpointu. Rozróżnienie tych kodów zapobiega naprawianiu adresu, gdy rzeczywistą przyczyną jest metoda lub autoryzacja.
Śledzenie adresu od aplikacji do serwera
Diagnozę warto rozpocząć od porównania żądania generowanego przez program z aktualną dokumentacją API. Trzeba zweryfikować bazowy adres usługi, protokół http lub https, numer portu, prefiks ścieżki, wersję interfejsu, nazwę zasobu i sposób przekazywania identyfikatora. Należy też sprawdzić, czy aplikacja nie dokleja ścieżki dwukrotnie, na przykład tworząc adres /api/api/v1/status, albo nie usuwa fragmentu wymaganego przez reverse proxy. W systemach korzystających ze zmiennych konfiguracyjnych częstym źródłem błędu jest stara wartość adresu bazowego pozostawiona po zmianie środowiska.
Do odtworzenia problemu można użyć narzędzia klienta HTTP, na przykład polecenia curl -i -X GET "https://api.example.com/v1/status". Opcja -i pokazuje nagłówki i kod odpowiedzi, dzięki czemu można sprawdzić, czy odpowiedź pochodzi bezpośrednio z aplikacji, bramy API, serwera proxy czy urządzenia filtrującego ruch. Trzeba zachować tę samą metodę, ścieżkę, parametry i istotne nagłówki co w uszkodzonej aplikacji, ale nie należy ujawniać tokenów dostępowych w logach ani w zgłoszeniach. Jeżeli ręczne żądanie działa, a aplikacja otrzymuje 404, różnica zwykle znajduje się w konfiguracji klienta, składaniu URL albo środowisku uruchomieniowym. Jeżeli oba żądania kończą się tak samo, należy sprawdzić trasę wdrożoną na serwerze i wersję dokumentacji.
Warto również przeanalizować przekierowania. Przejście z adresu z końcowym ukośnikiem na adres bez ukośnika może być obsługiwane przez jedną konfigurację, ale nie przez inną. Automatyczne podążanie za przekierowaniem może dodatkowo zmienić metodę żądania albo ukryć pierwotny adres, dlatego podczas testu należy odnotować kody 3xx i nagłówek Location. Dla endpointów zawierających parametry ścieżki trzeba potwierdzić, że identyfikator jest kodowany poprawnie i nie jest pusty. Błędne kodowanie znaków specjalnych może spowodować, że serwer potraktuje żądanie jako inną trasę.
Usuwanie przyczyny w komputerze i konfiguracji aplikacji
Naprawa polega na ujednoliceniu adresu używanego przez klienta z adresem faktycznie wystawionym przez API. Zmianę należy wykonać w jednym, jasno określonym miejscu konfiguracji, a następnie uruchomić test obejmujący poprawny endpoint, oczekiwany kod odpowiedzi i podstawową strukturę danych. Nie powinno się maskować problemu przez bezwarunkowe traktowanie odpowiedzi 404 jako pustej listy, ponieważ aplikacja może wtedy wyświetlić brak danych zamiast poinformować o awarii komunikacji. Obsługa błędu powinna rozróżniać nieistniejący adres, niedostępność serwera, błędną metodę i brak uprawnień.
Jeżeli błąd pojawił się po aktualizacji programu, należy porównać wersję klienta, konfigurację środowiskową oraz wersję API. Udokumentowane wersjonowanie, na przykład przez prefiks /v1 lub /v2, nie oznacza, że wszystkie endpointy z jednej wersji występują w drugiej. W przypadku lokalnego problemu trzeba sprawdzić ustawienia DNS, proxy, zapory sieciowej i pliku konfiguracyjnego, ale sam komunikat 404 sugeruje, że żądanie najczęściej dotarło do jakiegoś serwera. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i podzespołów, w tym diagnostyką konfiguracji aplikacji oraz problemów z komunikacją programów z usługami sieciowymi.
Po poprawieniu endpointu warto pozostawić w logach adres bazowy bez sekretów, metodę HTTP, ścieżkę, kod odpowiedzi, czas trwania żądania i identyfikator korelacyjny. Takie dane pozwalają połączyć zdarzenie po stronie programu z wpisem w logach serwera. Nie należy zapisywać pełnych nagłówków autoryzacyjnych ani kluczy API. Jeżeli trasa została zmieniona celowo, poprawne rozwiązanie obejmuje aktualizację klienta i dokumentacji, a także sprawdzenie, czy stare wywołania są obsługiwane kontrolowanym komunikatem o zakończeniu wersji. Dzięki temu kolejny błąd adresu można odróżnić od awarii sieci, problemu z uprawnieniami lub niezgodności danych.
