Екрану пошуку потрібні не лише результати або помилка

Сценарій екранів, а не показник стану сервісу

Це запропоновані стани туристичного застосунку, який належить розробникові. Вони не є збереженими відповідями API, демонстраціями робочих екранів чи доказом доступності записів про офлайн-карти. Мандрівник користується вашим застосунком; оператор API-облікового запису керує ключем сервісу й кредитами. Кожному потрібна інформація, з якою він може щось зробити.

Перед першим пошуком поясніть, що функція читає історичні обговорення. Запропонований запит на кшталт offline maps допомагає почати, але не показуйте вигаданих рекомендацій так, ніби пошук уже відбувся. Залиште явну дію «Пошук», щоб введення тексту й перегляд форми самі по собі не запускали платний запит.

Завантаження: запитання має залишатися видимим

Поки запит очікує відповіді, зберігайте надіслану фразу й вибрані фільтри. Позначайте область результатів як завантаження, запобігайте повторному надсиланню цієї дії та додавайте доступний текстовий підпис до анімації. Сама затримка не визначає ні збою сервісу, ні його причини.

Якщо людина змінює запит до надходження попередньої відповіді, пов’язуйте кожну відповідь із надісланим вводом. Не підставляйте мовчки результати старого запитання під нове. Це вибір реалізації, який слід перевірити в застосунку, а не поведінка впорядкування чи скасування, яку надає архівний API.

Успішна відповідь може містити записи або нічого

Коли записи повернено, показуйте лише доступні поля та позначайте матеріал як історичний. Коментар може не мати заголовка, а відсутня дата має залишатися невідомою. Описуйте видиму сторінку, а не оголошуйте точну кількість збігів, якщо pagination.relation має значення gte або unknown.

Успішна порожня відповідь — окремий результат. Можливе повідомлення: «Цей запит не повернув записів». Запропонуйте свідомо змінити формулювання або фільтри, зберігши поточний ввід. Не стверджуйте, що такого обговорення ніде немає. Успішний порожній запит однаково коштує один кредит.

Для 400, 401 і 402 потрібні різні відповідальні

HTTP 400 означає неправильні параметри запиту. Перевірте справжню проблему: прикладами є непідтримуваний параметр, сторінка за межами діапазону або дата не у форматі YYYY-MM-DD. За потреби поясніть мандрівникові, яке поле виправити, а помилки контракту бекенду залишайте в діагностиці оператора.

HTTP 401 означає відсутній або недійсний API-ключ сервісу. Це не встановлює, що сесія мандрівника в застосунку завершилася, і для цих ключів не документовано механізму закінчення строку за часом. Оператор перевіряє збережений ключ відповідного домену та нещодавню регенерацію. Не просіть мандрівника вводити ключ або входити в обліковий запис сервісу.

HTTP 402 означає недостатню кількість кредитів в обліковому записі сервісу. Мандрівникові можна показати: «Пошук обговорень тимчасово призупинено». Оператор може увійти в розділ «Ключ і кредити» й перевірити баланс. Новий запит — окрема дія після усунення причини; просте повторення попереднього не є розв’язанням.

429, помилка джерела та невідомий результат доставки

HTTP 429 означає досягнення обмеження частоти. Дотримуйтеся Retry-After, зменшуйте повторні надсилання та дозволяйте людині спробувати знову, коли це доречно. Обмеження може стосуватися спільного бекенду чи облікового запису, тому не звинувачуйте окремого мандрівника. Не запускайте необмежений цикл автоматичних повторів.

Шлюз повідомляє про помилки сервера-джерела кодом HTTP 502. Зберігайте запитання та показуйте явну можливість повторити без обіцянки успіху наступної спроби. Зарезервований кредит повертається після невдалого запиту до джерела; відповідь також може повідомляти про очікування звіряння. Якщо застосунок утратив усю відповідь, остаточний результат оплати невідомий: сервер міг завершити запит успішно.

Публічний маршрут /v1/status повертає статичне пояснення призначення сервісу та показує, що HTTP-обробник відповідає. Він не перевіряє пошук в архіві й не засвідчує справність сервера-джерела. Спирайте робочі рішення на фактичний результат запиту. Повний сценарій є в розділі «Сценарій застосунку», а варіанти реалізації — у практичній нотатці «Екрани завантаження, порожнього результату та помилки».