API без результату та API з помилкою вимагають різного підходу. Успішний пошук може не повернути жодного місця у запитаній зоні. Мережева помилка, досягнення ліміту або недоступність джерела унеможливлюють зробити висновок на основі пошуку.
Для ROOTE перевірте спочатку HTTP-відповідь, потім бізнес-статус, очікувану колекцію та покриття. Цей підхід запобігає відображенню «немає туалетів», коли виклик Сервісів провалився, або «немає зупинок» після перевищення часу очікування.
Читання трьох рівнів відповіді
| Рівень | Що перевіряти | Можливі висновки |
|---|---|---|
| Транспорт | Підключення, тайм-аут і HTTP-статус | Чи запит успішний? |
| Контракт | Дійсний JSON, версія та очікувані поля | Чи придатна відповідь для використання? |
| Бізнес-результат | status, collections, coverage, warnings і meta | Що відомо у запитаному периметрі? |
HTTP-код 200 не достатній для підтвердження пошуку. Відповідь може містити статус partial або 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 Сервісів використовує types=toilets; URL карти — modes=toilets. Ці параметри належать до різних контрактів.
Потім розширюйте лише один параметр за раз: збільшуйте радіус у межах маршруту або видаляйте фільтр для явного тесту. Зберігайте початковий запит. Якщо розширюєте автоматично, повідомляйте користувачу новий периметр.
Побудова пошуку API на основі GPS-координат
Обробка недоступного джерела без втрати інших
Часткова відповідь може містити місця з джерел, які відповіли, хоча інше не вдалося. Зберігайте ці результати, їхні атрибути і відповідні застереження. Не представляйте список як повний і не замінюйте відсутні поля оманливими значеннями за замовчуванням.
Старі дані у кеші теж можуть бути корисні, якщо ваша політика допускає таке резервне використання. Вони мають залишатися позначеними як застарілі. Час отримання вашого запиту не молодить початкове спостереження.
Адаптація повідомлень і відновлення
| Ситуація | Повідомлення для адаптації в інтерфейсі | Дія |
|---|---|---|
| empty | У цій зоні та з цими фільтрами не повернено жодних результатів | Змінити зону або фільтри |
| partial | Деякі результати доступні; пошук неповний | Відобразити результати і застереження |
| Помилка валідації | Пошук містить недійсний параметр | Виправити запит |
| Аутентифікація чи права | Цей доступ не дозволяє цей пошук | Перевірити обліковий запис або токен |
| Ліміт або недоступність | Пошук тимчасово недоступний | Дотримуватися інструкцій відновлення |
У разі 429 звертайтеся до вказівок сервісу і можливого Retry-After. Помилка 400 вимагає виправлення аргументів; повторення того самого запиту не вирішує проблему. Не перетворюйте 401 на автоматичний анонімний виклик, якщо користувач надав токен.
Перевірте всі чотири стани перед публікацією
Підготуйте повні, порожні, часткові та помилкові тестові відповіді, а також недійсний JSON і перевищення часу. Перевірте відображуване повідомлення, збережені результати та кількість повторів. Головне — збій ніколи не повинен видавати твердження про відсутність сервісів.
Застосування цих правил до ІІ асистента
Розуміння форматів мобільних даних
Поширені запитання
Чи доводить порожній список відсутність туалетів?
Ні. Це лише вказує, що за цим пошуком і перевіреними джерелами не отримано результатів.
Чи можна показати часткову відповідь?
Так, якщо використані сутності валідні і збережено потрібні застереження і ліміти.
Чи слід повторювати кожну помилку?
Ні. Виправляйте помилки параметрів чи доступу; обмежуйте повтори для тимчасових інцидентів і дотримуйтесь інструкцій сервісу.