API bez výsledku a API s chybou vyžadují odlišný přístup. Úspěšné vyhledávání nemusí vrátit žádné místo v požadovaném rozsahu. Síťová chyba, dosažení limitu nebo nedostupnost zdroje naopak zabraňují závěru ze samotného vyhledávání.
Pro ROOTE zkontrolujte odpověď HTTP, poté stav obchodní logiky, očekávanou kolekci a pokrytí. Tento postup zabrání zobrazování zpráv typu „žádné toalety“, pokud selhal volání služby, nebo „žádná zastávka“ po vypršení časového limitu.
Čtení tří úrovní odpovědi
| Úroveň | Co zkontrolovat | Možný závěr |
|---|---|---|
| Přenos | Připojení, časový limit a HTTP stav | Dokončil se požadavek úspěšně? |
| Smlouva | Platný JSON, verze a očekávaná pole | Je odpověď využitelná? |
| Výsledek obchodní logiky | status, kolekce, pokrytí, varování a meta | Co víme v požadovaném rozsahu? |
HTTP kód 200 nestačí k potvrzení vyhledávání. Odpověď může signalizovat částečný průběh nebo stav error. Naopak, 404 na cestě není běžný způsob vyjádření prázdné kolekce: zkontrolujte URL a smlouvu.
Pochopení statusů success, empty, partial a error
| Stav | Doporučené zpracování |
|---|---|
| success | Zobrazit entity po ověření a zachovat limity |
| empty | Upozornit, že vyhledávání nevrátilo žádný výsledek |
| partial | Zobrazit použitelné informace s příslušnými varováními |
| error | Prezentovat vyhledávání jako nedostupné; nezávěrujte absenci míst |
Absence výsledku se vztahuje k dotazu a známým zdrojům. Neznamená fyzickou neexistenci služeb. Neúplné pokrytí, restriktivní filtr nebo aplikovaný limit mohou snížit počet výsledků.
Rozhodovací strom pro vaše rozhraní
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.Kontrola parametrů ve správném pořadí
Nejdříve zkontrolujte zeměpisnou šířku a délku, jejich pořadí a získané město. Poté ověřte jednotku poloměru a slovník filtrů. API Služby používá types=toilets; URL mapy používá modes=toilets. Tyto parametry patří do různých smluv.
Postupně rozšiřte jen jeden rozměr: zvětšete poloměr v mezích cesty nebo odstraňte filtr pro jasný test. Uchovejte původní dotaz. Pokud automaticky rozšiřujete, informujte uživatele o novém rozsahu.
Vytvoření API vyhledávání kolem GPS souřadnic
Zpracování nedostupného zdroje bez ztráty ostatních
Částečná odpověď může obsahovat místa ze zdrojů, které odpověděly, zatímco jiné selhaly. Zachovejte tyto výsledky, jejich atributy a odpovídající varování. Neprezentujte seznam jako úplný a nenahrazujte chybějící pole klamavými výchozími hodnotami.
I stará informace v cache může být užitečná, jestliže vaše politika tento fallback povoluje. Musí ale být označena jako zastaralá. Čas přijetí vašeho požadavku nevykresluje pozorování na novější.
Přizpůsobení zpráv a obnovy
| Situace | Zpráva přizpůsobená vašemu rozhraní | Akce |
|---|---|---|
| empty | V této oblasti s danými filtry nebyl vrácen žádný výsledek | Změnit oblast nebo filtry |
| partial | Některé výsledky jsou dostupné; vyhledávání je neúplné | Zobrazit výsledky a varování |
| Chyba validace | Vyhledávání obsahuje neplatný parametr | Opravit dotaz |
| Autentizace nebo oprávnění | Tento přístup neumožňuje toto vyhledávání | Zkontrolovat účet nebo token |
| Limit nebo nedostupnost | Vyhledávání je dočasně nedostupné | Dodržovat pokyny pro opakování |
Pro 429 dodržujte pokyny služby a případné Retry-After. Chyba 400 vyžaduje opravu argumentů; opakování stejného dotazu ji nevyřeší. Neprovádějte anonymní volání při 401, pokud uživatel poskytl token.
Referenční chybové kódy API ROOTE
Testujte všechny čtyři stavy před zveřejněním
Připravte kompletní testovací odpovědi: plné, prázdné, částečné a chybové, také neplatný JSON a překročení limitu. Zkontrolujte zobrazenou zprávu, zachované výsledky a počet opakování. Hlavním testem je, aby výpadek nikdy nezpůsobil tvrzení o absenci služeb.
Aplikace těchto pravidel na AI asistenta
Pochopení formátů dat mobility
Často kladené otázky
Dokazuje prázdný seznam absenci toalet?
Ne. Pouze znamená, že pro toto vyhledávání a zdroje nebyl vrácen žádný výsledek.
Lze zobrazit částečnou odpověď?
Ano, pokud jsou použité entity platné a zachováte příslušná varování a limity.
Je třeba opakovat každou chybu?
Ne. Opravte chyby v parametrech nebo přístupu; omezte opakování pouze na přechodné problémy a dodržujte pokyny služby.