Reddit App API · 03 / APP
Поисковому экрану нужны не только результаты и ошибка
Разделите загрузку, успешный пустой ответ и ошибки в предлагаемом туристическом приложении. Дайте читателям понятные сообщения, а операторам — подходящие действия диагностики.
Ваш экран
Готово
Вымышленный локальный пример. Запрос не отправляется.
{
"request_sent": false
}Ваш экран
Загрузка
Вымышленный локальный пример. Запрос не отправляется.
{
"request_in_flight": true
}Ваш экран
Записи
Вымышленный локальный пример. Запрос не отправляется.
{
"data": [
{
"id": "fictional-001",
"kind": "post",
"title": "offline maps",
"text": "Вымышленный локальный пример. Запрос не отправляется.",
"subreddit": "hiking",
"score": 7,
"created_utc": 1704067200
}
],
"pagination": {
"page": 1,
"limit": 3,
"total": 1,
"relation": "eq",
"has_more": false,
"window_exhausted": false,
"truncated": false
},
"credits": {
"cost": 1,
"balance": 99
}
}Ваш экран
Нет результатов
Вымышленный локальный пример. Запрос не отправляется.
{
"data": [],
"pagination": {
"page": 1,
"limit": 3,
"total": 0,
"relation": "eq",
"has_more": false,
"window_exhausted": false,
"truncated": false
},
"credits": {
"cost": 1,
"balance": 99
}
}Ваш экран
401 · invalid_api_key
Вымышленный локальный пример. Запрос не отправляется.
{
"error": "invalid_api_key"
}Ваш экран
402 · insufficient_credits
Вымышленный локальный пример. Запрос не отправляется.
{
"error": "insufficient_credits"
}Ваш экран
429 · rate_limited
Вымышленный локальный пример. Запрос не отправляется.
{
"error": "rate_limited"
}Ваш экран
502 · upstream_unavailable
Вымышленный локальный пример. Запрос не отправляется.
{
"error": "upstream_unavailable"
}Вымышленный локальный пример. Запрос не отправляется.
Сценарий экранов, а не табло состояния сервиса
Это предлагаемые состояния туристического приложения, принадлежащего разработчику. Они не являются сохранёнными ответами 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-обработчик отвечает. Он не проверяет архивный поиск и не подтверждает работоспособность вышестоящего сервиса. Основывайте рабочие решения на фактическом исходе запроса. Полный сценарий есть в разделе «Сценарий приложения», а варианты реализации — в заметке «Экраны загрузки, пустого ответа и ошибки».
