検索画面には結果とエラー以外の状態も必要

サービス監視画面ではなく、画面遷移の設計案

ここで扱うのは開発者自身が作るハイキングアプリの状態案です。取得したAPIレスポンスや動作画面の実演ではなく、オフライン地図のレコードが存在する証拠でもありません。利用者はアプリを使い、APIアカウントの運用担当者はサービスの認証情報とクレジットを管理します。それぞれが対応できる情報を提示してください。

最初の検索より前に、過去の議論を読む機能であることを説明します。offline mapsのようなクエリ候補は入力の助けになりますが、まだ検索していないのに架空のおすすめを検索済みの結果として見せてはいけません。明示的な「検索」操作を用意し、入力やフォームの閲覧だけで課金対象のリクエストが発生しないようにします。

読み込み中も疑問を見える位置に残す

リクエストの応答を待っている間は、送信したクエリと選択したフィルターを保持します。結果欄を読み込み中と示し、同じ操作の重複送信を防ぎ、アニメーションだけでなく利用しやすいテキストの説明も添えてください。遅延したというだけでは、サービス障害やその原因は分かりません。

前のレスポンスが届く前にクエリを変更した場合は、各レスポンスを送信時の入力と結び付けます。古い疑問への結果を新しい疑問の下に黙って表示してはいけません。これはテストすべきアプリ側の実装判断であり、アーカイブAPIが提供する順序制御やキャンセル機能ではありません。

成功時にも、レコードがある場合とない場合がある

レコードが返されたら、存在するフィールドだけを表示し、過去の資料だと分かるようにします。コメントにはタイトルがないこともあり、日付が欠けていれば不明のままにします。pagination.relationがgteまたはunknownなら、厳密な一致総数を表示せず、今見えているページについて説明してください。

正常な空のレスポンスは独立した結果です。「このリクエストではレコードが返されませんでした」という案内が考えられます。入力を残したまま、語句やフィルターを利用者が意図して変更できるようにしてください。そのような議論はどこにもない、と主張してはいけません。空でも正常な取得は1クレジットを消費します。

400、401、402では対応する人が違う

HTTP 400はリクエスト入力の不備を示します。未対応のパラメーター、範囲外のページ、YYYY-MM-DD形式でない日付など、実際の問題を確認してください。利用者が修正できる項目なら説明し、バックエンドと仕様の不一致は運用担当者向けの診断情報に残します。

HTTP 401はサービスのAPIキーがないか、無効であることを示します。利用者のアプリ内セッションが期限切れになった証拠ではありません。また、このAPIキーに有効期限で自動失効する仕組みは定められていません。運用担当者が、保存したドメイン固有のキーと最近の再生成の有無を確認します。利用者にキーの入力やサービスアカウントへのログインを求めないでください。

HTTP 402はサービスアカウントのクレジット不足を示します。利用者向けには「議論の検索を一時停止しています」などと伝えられます。運用担当者は「キーとクレジット」にログインして残高を確認します。原因を解消してから新しいリクエストを実行してください。以前のリクエストをただ繰り返しても解決にはなりません。

429、上流障害、配送結果が不明な状態

HTTP 429はレート制限への到達を示します。Retry-Afterに従い、重複送信を減らし、適切な時点で再試行できるようにしてください。制限の対象が共用バックエンドやアカウントの場合もあるため、個々の利用者のせいにしないようにします。無制限の自動再試行ループを作ってはいけません。

ゲートウェイは上流の失敗をHTTP 502で報告します。クエリを保持し、次の試行が成功すると約束せずに、明示的な再試行操作を示してください。上流リクエストが失敗すれば予約済みクレジットは返還されますが、レスポンスが照合処理待ちを示す場合もあります。アプリがレスポンスを完全に失った場合は、最終的な課金結果は不明です。サーバー側では正常に完了している可能性があります。

公開の/v1/statusは、サービス範囲の固定情報を返し、HTTPハンドラーが応答したことを示します。アーカイブ検索を試したり、上流の健全性を証明したりはしません。運用上の判断には実際のリクエスト結果を使ってください。画面遷移全体は「アプリの流れ」、実装の判断は実装ノートの「読み込み中・結果なし・エラーの画面」を参照してください。