API bez wyniku i API z błędem wymagają dwóch różnych działań. Udane zapytanie może nie zwrócić żadnego miejsca w przeszukiwanym obszarze. Natomiast błąd sieci, osiągnięcie limitu lub niedostępne źródło uniemożliwiają wyciągnięcie wniosków z wyszukiwania.
Dla ROOTE najpierw sprawdź odpowiedź HTTP, potem status biznesowy, oczekiwaną kolekcję i pokrycie danych. Podejście to zapobiega wyświetlaniu „brak toalety”, gdy wywołanie Usług zawiodło lub „brak przystanku” po przekroczeniu czasu oczekiwania.
Odczytanie trzech poziomów odpowiedzi
| Poziom | Co kontrolować | Możliwe wnioski |
|---|---|---|
| Transport | Połączenie, czas oczekiwania i status HTTP | Czy żądanie się powiodło? |
| Kontrakt | Poprawny JSON, wersja i oczekiwane pola | Czy odpowiedź jest użyteczna? |
| Wynik biznesowy | status, kolekcje, pokrycie, ostrzeżenia i meta | Co wiadomo o żądanym obszarze? |
Kod HTTP 200 nie gwarantuje poprawnej wyszukiwarki. Odpowiedź może zawierać wykonanie częściowe lub status error. Natomiast 404 dla trasy nie jest normalnym sposobem oznaczania pustej kolekcji: sprawdź URL i kontrakt.
Zrozumienie success, empty, partial i error
| Status | Zalecane działanie |
|---|---|
| success | Wyświetl encje po walidacji i zachowaj limity |
| empty | Poinformuj, że wyszukiwanie nie zwróciło wyników |
| partial | Wyświetl dane użyteczne z odpowiednimi ostrzeżeniami |
| error | Przedstaw, że wyszukiwanie jest niedostępne; nie wyciągaj wniosku o braku miejsc |
Brak wyniku dotyczy zapytania i znanych źródeł. Nie dowodzi fizycznego braku usługi. Niepełne pokrycie, restrykcyjny filtr lub nałożony limit mogą zmniejszyć liczbę wyników.
Drzewo decyzyjne dla twojego interfejsu
1. La requête a-t-elle abouti ?
Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
Oui → aucun résultat retourné dans ce périmètre.
Non → afficher les résultats et leurs limites.Sprawdzaj parametry we właściwej kolejności
Najpierw zweryfikuj szerokość i długość geograficzną, ich kolejność oraz uzyskane miasto. Następnie sprawdź jednostkę promienia i słownictwo filtrów. API Usługi używa types=toilets; URL mapy używa modes=toilets. Te parametry należą do różnych kontraktów.
Następnie rozszerzaj pojedynczy wymiar po kolei: zwiększ promień w granicach trasy lub usuń filtr dla wyraźnego testu. Zachowaj ślad zapytania początkowego. Jeśli rozszerzasz automatycznie, poinformuj użytkownika o nowym obszarze.
Budowanie zapytania API wokół współrzędnych GPS
Obsługa niedostępnego źródła bez tracenia innych
Odpowiedź częściowa może zawierać miejsca ze źródeł, które odpowiedziały, podczas gdy inne zawiodły. Zachowaj te wyniki, ich przypisania i istotne ostrzeżenie. Nie przedstawiaj listy jako kompletnej i nie zastępuj brakujących pól wprowadzającymi w błąd wartościami domyślnymi.
Starsze informacje przechowywane w pamięci podręcznej mogą być przydatne, jeśli polityka na to pozwala. Muszą być jednak oznaczone jako przestarzałe. Czas otrzymania twojego zapytania nie odświeża oryginalnej obserwacji.
Dostosowanie komunikatów i sposobów obsługi
| Sytuacja | Komunikat do dostosowania w interfejsie | Działanie |
|---|---|---|
| empty | Brak wyników w tym obszarze z podanymi filtrami | Zmień obszar lub filtry |
| partial | Dostępne są niektóre wyniki; wyszukiwanie jest niekompletne | Wyświetl wyniki i ostrzeżenie |
| Błąd walidacji | Zapytanie zawiera nieprawidłowy parametr | Popraw zapytanie |
| Uwierzytelnianie lub uprawnienia | Ten dostęp nie pozwala na takie wyszukiwanie | Sprawdź konto lub token |
| Limit lub niedostępność | Wyszukiwanie jest tymczasowo niedostępne | Przestrzegaj zasad ponawiania |
Dla 429 sprawdź zasady usługi i ewentualny Retry-After. Błąd 400 wymaga korekty argumentów; powtarzanie tego samego zapytania nic nie zmieni. Nie zmieniaj 401 w automatyczne anonimowe wywołanie, jeśli użytkownik dostarczył token.
Testuj cztery stany przed publikacją
Przygotuj kompletne, puste, częściowe i błędne odpowiedzi testowe, a także niepoprawny JSON i przekroczony limit czasu. Sprawdź komunikaty wyświetlane, zachowane wyniki i liczbę ponowień. Kluczowy test to, aby awaria nigdy nie wskazywała na brak usług.
Stosowanie tych zasad w asystencie AI
Zrozumienie formatów danych mobilności
Najczęściej zadawane pytania
Czy pusta lista dowodzi braku toalet?
Nie. Informuje tylko, że nie zwrócono wyników dla tego zapytania i przeszukanych źródeł.
Czy można wyświetlić odpowiedź częściową?
Tak, jeśli używane encje są ważne i zachowasz ostrzeżenia oraz potrzebne ograniczenia.
Czy należy powtarzać każde błędy?
Nie. Popraw błędy parametrów lub dostępu; ogranicz ponawianie do incydentów tymczasowych i przestrzegaj zasad usługi.