スピナーを描く前に状態を書き出す
これは開発者が作るハイキングアプリの流れの提案であり、観測したAPIの動作記録ではありません。利用者がoffline mapsと入力し、過去の議論を要求して待つ場面を考えます。未操作のフォーム、応答待ち、レコードあり、正常な空のレスポンス、失敗を区別する必要があります。何もないパネル1つでは、これらの違いは伝わりません。
最初は何を検索するかを説明する、中立的な待機画面にします。入力するだけでリクエストを送る必要はありません。明示的に送信されたら、そのリクエストと疑問を一緒に保存し、読み込み中と表示します。入力を読める状態に保ち、連打によって同じ操作を何度も送らないようにしてください。スピナーは待っていることを伝えるもので、アーカイブ内の処理進捗を示す証拠ではありません。
遅れて届いたレスポンスも元の疑問に結び付ける
offline mapsのリクエストを待つ間に、利用者が入力を「ダウンロード済みの地域」に変えたとします。これは操作を考えるための例であり、検索して得た結果ではありません。アプリは待機を続けるか、別のリクエストを始めるか、画面上の処理を取り消せるようにするかを決めます。どの設計でも、前のレスポンスを新しい語句への回答として黙って表示してはいけません。
アプリ自身の状態管理で、各リクエストと送信した入力を関連付けます。レスポンスが届いたら、今の画面に属するものか確認してください。遅れたレスポンスを画面から除外することと、サーバーの処理を取り消すことは別です。すでに送信したリクエストは正常に完了し、課金される可能性があります。この違いを自分の実装でテストしてください。
正常な空のレスポンスも結果として扱う
レコードが返ったら、実際に存在するフィールドを表示し、過去の資料という表示を保ちます。data配列が空なら、そのリクエストではレコードが返らなかったと別のメッセージで説明します。語句やフィルターを残したまま編集できるようにし、読み手が変更の理由を判断できるようにしてください。空の結果を架空の人気投稿で置き換えてはいけません。
正常な空の取得も、レコードがある正常なレスポンスと同じく1クレジットを消費します。だからこそ、結果なしをエラーとして隠すのではなく、クエリを意図して変更できる設計が必要です。関連する議論がどこにもない、と断定するメッセージは避けてください。アーカイブは不完全であり、そのレスポンスは特定のクエリと限られた取得範囲に対するものです。
技術的な問題は運用担当者へ伝える
400レスポンスではリクエスト入力を確認します。アプリが不正な日付や未対応のパラメーターを送ったなら、バックエンドの仕様違反を利用者の責任にしないでください。401はサービスキーの欠如や無効を示します。アプリを再読み込みしたり、利用者にログインを求めたりしても、その認証情報が直るとは限りません。
402はサービスアカウントのクレジット不足です。利用者に請求書を表示するのではなく、運用担当者の判断につなげます。429ではRetry-Afterに従い、リクエストの繰り返しを減らします。複数の読み手でアカウントを共有している可能性があるため、その人が制限の原因だと自動的に決めつけないでください。
分かっている失敗と、結果が不明な状態を分ける
上流の取得に失敗すると、ゲートウェイは502を返します。予約済みクレジットは解放されるか、照合処理待ちと報告されます。クエリと、それまで表示していたページを保持し、範囲を限った再試行を選べるようにします。自動再試行を繰り返しても、何が起きたかを読み手が理解する助けにならず、リクエストを増やすことがあります。
アプリにレスポンスが届かなければ、サーバーで失敗したのか正常に完了したのか分からない場合があります。後で照合できるよう不明であることを記録し、返還済みや成功と断定して表示しないでください。公開の/v1/statusは固定のサービス範囲とHTTP応答の確認であり、その疑問を解消したり、アーカイブ検索の健全性を証明したりはできません。
スクリーンショットだけでなく状態遷移を確認する
アプリの責任者と一緒に、送信、待機中の編集、空の結果、失敗後の再試行、次ページの読み込み、画面からの離脱という流れを確認します。各遷移で、保持する入力、表示する内容、次の操作を明らかにしてください。見栄えのよい画面案があっても、その遷移が動く証拠にはなりません。
運用担当者向けの診断、生のサービスレスポンス、認証情報を一般利用者向けメッセージに混ぜないでください。議論を読む機能が使えなくても、旅の準備を続けられるだけの状況説明をします。この状態遷移に関わるリクエスト予算と「さらに表示」の判断は/ja/#field-notesを参照してください。
