API без резултат и API с грешка изискват различна обработка. Успешното търсене може да не върне нито едно място в търсената зона. От друга страна, мрежова грешка, достигнат лимит или недостъпна източник не позволява да се направи извод от търсенето.
За ROOTE проверете HTTP отговора, след това бизнес статус, очакваната колекция и обхвата. Тази процедура предотвратява показването на „без тоалетни“, когато услугата е неуспешна, или „без спирки“ след изтичане на времето за чакане.
Четене на трите нива на отговор
| Ниво | За проверка | Възможен извод |
|---|---|---|
| Транспорт | Връзка, време за отговор и HTTP статус | Изпълни ли се заявката успешно? |
| Договор | Валиден JSON, версия и очаквани полета | Може ли отговорът да бъде използван? |
| Бизнес резултат | status, collections, coverage, warnings и meta | Какво знаем в търсената зона? |
HTTP код 200 не е достатъчен за валидиране на търсене. Отговорът може да сигнализира частично изпълнение или статус error. Обратно, 404 на маршрут не е нормален начин да се изрази празна колекция: проверете URL и договора.
Разбиране на success, empty, partial и error
| Статус | Препоръчителна обработка |
|---|---|
| success | Покажете обектите след валидиране и запазете ограниченията |
| empty | Посочете, че няма върнати резултати за това търсене |
| partial | Покажете използваемата информация с предупрежденията ѝ |
| error | Представете търсенето като недостъпно; не правете извод за липсата на места |
Липсата на резултат се отнася за известна заявка и източници. Тя не доказва, че няма физически услуга. Недостатъчният обхват, строг филтър или приложено ограничение могат да намалят резултатите.
Решаващо дърво за вашия интерфейс
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.Проверете параметрите в правилния ред
Първо проверете ширината и дължината, техния ред и получения град. След това проверете мерната единица на радиуса и езика на филтрите. API Services използва types=toilets; URL на карта използва modes=toilets. Тези параметри принадлежат към различни договори.
После разширявайте само едно измерение наведнъж: увеличете радиуса в рамките на маршрута или премахнете филтър за явен тест. Запазете първоначалната заявка. Ако разширявате автоматично, уведомете потребителя за новата зона.
Конструиране на API търсене около GPS координати
Обработка на недостъпен източник без загуба на други
Частичен отговор може да съдържа места от източници, които са отговорили, докато други са се провалили. Запазете тези резултати, тяхното приписване и съответното предупреждение. Не представяйте списъка като изчерпателен и не попълвайте липсващи полета с подвеждащи подразбиращи се стойности.
Съхранена стара информация в кеш също може да е полезна, ако политиката ви позволява това прибягване. Тя трябва да остане маркирана като стара. Времето на получаване на заявката не подмладява оригиналната наблюдение.
Адаптиране на съобщенията и повторните опити
| Ситуация | Съобщение за адаптиране към вашия интерфейс | Действие |
|---|---|---|
| empty | Няма върнати резултати в тази зона с тези филтри | Променете зоната или филтрите |
| partial | Налични са някои резултати; търсенето е непълно | Покажете резултатите и предупреждението |
| Грешка при валидиране | Търсенето съдържа невалиден параметър | Коригирайте заявката |
| Аутентикация или права | Този достъп не позволява това търсене | Проверете акаунта или токена |
| Ограничение или недостъпност | Търсенето е временно недостъпно | Спазвайте насоките за повторение |
При 429 проверете инструкциите на услугата и възможния Retry-After. Грешка 400 изисква корекция на аргументите; повторно изпълнение на същата заявка не го решава. Не превръщайте 401 в автоматично анонимно повикване, ако потребителят е предоставил токен.
Референция за грешки на ROOTE API
Тествайте четирите състояния преди публикуване
Подгответе пълни тестови отговори: пълни, празни, частични, с грешка, невалиден JSON и времево изтичане. Проверете показаното съобщение, запазените резултати и броя повторения. Основният тест е, че повреда никога не трябва да води до твърдение за липса на услуги.
Прилагане на тези правила към AI асистент
Разбиране на формати за мобилност на данни
Често задавани въпроси
Доказва ли празен списък липса на тоалетни?
Не. Той само показва, че няма върнати резултати за това търсене и разгледаните източници.
Може ли да се покаже частичен отговор?
Да, ако използваните обекти са валидни и вие запазвате необходимите предупреждения и ограничения.
Трябва ли да възобновявам всяка грешка?
Не. Коригирайте грешките в параметрите или достъпа; ограничете повторенията до временни проблеми и спазвайте инструкциите на услугата.