通信は、依頼と返事の往復

画面が動く場所と、データを受け取る場所は同じとは限りません。ボタンを押した後の通信を追うと、表示されない、保存できないといった問題を、調べられる大きさに分けられます。

この回は、しくみを読むことと、実際の結果を確かめる練習を組み合わせます。付属見本はブラウザーだけで保存する一人用の版です。アカウント・データベース・共有は拡張課題として扱います。

HTTPとAPI：どこに、何を頼むのか

読書メモのボタンを押すと、本の情報が増える。利用者が見るのは、この一回の操作です。裏では、ブラウザだけで一覧を書き換える場合と、離れた保存先へ通信する場合があります。アプリの見た目が同じでも、データが通る道は違います。まず、今回の操作がどちらなのかを確かめます。

HTTPは、Webで資源を受け渡す通信の決まりです。依頼する側をクライアント、依頼を受けて返事をする側をサーバーと呼びます。読書メモを開いているブラウザはクライアントになります。サーバーは物理的な箱一台とは限らず、必要に応じて複数の仕組みが処理を分担します。資料 HTTP

この役割の違いを、フロントエンドとバックエンドという言葉でも整理できます。フロントエンドは利用者が触る画面や、その場の操作を扱います。バックエンドはデータの保存や権限確認などを扱います。一つのアプリが両方を持つこともあります。ファイルが一緒に並んでいても、どこで実行されるかは確かめてください。

APIは、別のプログラムから使うための入口や取り決めです。この章ではHTTPを使うWeb APIを考えます。読書一覧を読む入口と、読書メモを追加する入口について、受け付ける入力と返す結果を決めます。入口の場所をエンドポイントと呼びます。画面のURLとAPIのURLが同じ形とは限りません。

依頼には、場所だけでなく、何をするかも含まれます。HTTPのメソッドは、その操作の種類を示します。GETは取得、POSTはデータを送る処理などに使います。『GET /api/notesで一覧を読む』のように、メソッドと場所を一組で見ると、操作が具体的になります。実際の意味はAPIの仕様と照らします。資料 HTTP

送るメモは、書名や感想を名前付きで並べたJSONという形式にできます。ここで、入力欄の名前とAPIが受け取る名前を合わせます。画面ではbookTitle、保存先ではtitleを期待していたら、同じ本の名前でもすれ違います。AIには、送るデータ一件と、返ってくるデータ一件を並べて説明してもらいます。

HTTPにはヘッダーという追加情報もあります。本文の形式や、認証のための情報などを伝えます。ただし、通信の調査画面には秘密の値が出ることがあります。学習用の報告では、メソッド、場所、状態番号、項目名だけを記録し、認証ヘッダーやCookieの値をコピーしないようにします。

APIを使ったからといって、外部の有料サービスが必ず増えるわけではありません。自分で用意したサーバーへの通信もAPIになり得ます。読書メモの試作では、外部の書籍検索を足す前に、自分の一覧を一件受け取る往復で仕組みをつかみます。自分で期待する結果を書けると、通信の成否を判断しやすくなります。

図を描くなら、ブラウザ、API、保存先を置き、送る項目と返す項目を添えます。画面がその場で変わる部分も、通信が必要な部分も書き込みましょう。『ボタンを押すと何が起きるか』をこの図で話せるようになると、AIの提案を見たときに、必要のない通信まで増やしていないか確認できます。

通信の道を説明してもらう

まちの読書メモの追加ボタンから、保存先までの処理を説明してください。
ブラウザ内の処理とサーバーで実行する処理を分け、通信があればメソッド、URL、送る項目名を示してください。
本の情報一件を入力例にして、返ってくる結果を示してください。秘密の設定値は出力しないでください。

手を動かす順番

• 操作の後に通信があるかを調べる
• クライアントとサーバーの役割を図にする
• メソッドと入口と項目名を一組で読む
• 入力一件と期待する返事を並べる

返事とエラー：失敗した場所を狭める

追加ボタンを押しても、一覧が変わりません。こんなとき、すべてのファイルを直す依頼から始めると、原因を隠す変更まで入り込みます。ボタンの操作が受け取られたか、通信が出たか、返事が来たか、その返事を画面へ反映したか。この順に、どこで止まったかを調べます。

ブラウザの開発者ツールにあるNetworkの表示は、通信を調べる手がかりです。検証する操作を一回だけ行い、その直後の通信を見ます。URL、メソッド、状態番号、送受信の項目を確認します。何件もまとめて操作すると、どの通信がそのボタンに対応するかを見失いやすくなります。

HTTPの返事には状態番号があります。200番台は成功、400番台は依頼に関係する問題、500番台はサーバー側の問題を表します。404は対象が見つからない状態です。401は認証が必要な状態、403はアクセスを拒む状態を示します。番号は調査の入口であり、詳しい原因は返事の内容や記録も見ます。資料 HTTP_STATUS

番号が成功でも、期待するメモが保存されたとは限りません。APIが返した一件のIDや書名を確認し、一覧を読み直して同じ内容があるかを確かめます。保存せずに成功を返す実装も、間違えた保存先へ書く実装も作れてしまいます。状態番号と、利用者が確かめられる結果を組み合わせます。

JavaScriptのfetchは、通信失敗などでは失敗を返しますが、サーバーが404などの返事をしただけでは、その扱いになりません。返事の状態をresponse.okなどで別に確認する必要があります。AIには、通信そのものの失敗と、サーバーが返した失敗を両方扱っているか尋ねます。資料 FETCH

読書メモの画面にも、失敗したことを伝える場所を用意します。保存中なら待っていると分かる表示、失敗したら入力を残して再度試せる表示です。押した瞬間に『保存しました』と出すと、通信が失敗しても利用者は閉じてしまいます。返事を受け取る前、成功した後、失敗した後を分けて設計します。

返事が遅いときの二度押しも確かめます。同じメモが二件になったら、保存中のボタン制御と、APIが同じ依頼を重ねて受けた場合の扱いを相談します。通信が切れた後は、サーバーで保存済みなのに返事だけ届かなかった可能性もあります。再送する前に一覧を読み直すなど、重複しにくい手順を決めます。

別のサイトへ通信すると、CORSというブラウザの制約が関係することがあります。相手のサーバーが、どの出所の画面から読み取れるかをヘッダーで示す仕組みです。CORSは利用者ごとの閲覧権限を決める認証の代わりにはなりません。エラーを消すためだけに、許可範囲を一律に広げないでください。資料 CORS

AIへ渡す不具合メモは短くても具体的にできます。『題名を入れて送った。追加されるはずだったが400が返った』なら、入力条件を調べられます。『送信されず、画面も変わらない』ならボタン側から見ます。秘密の値を除き、操作、期待、実際、通信の結果を一組にすると、次の調査が小さくなります。

調査に使える不具合メモ

操作：練習用の書名と感想を一件追加した。期待：保存後、一覧に一件増える。
実際：保存中の表示が消えたが一覧は変わらない。通信：POST /api/notesは200だった。
返事の項目と一覧の再取得を、秘密の値を出さずに調べてください。原因が分かる前に、全体を書き直さないでください。

手を動かす順番

• 検証する操作を一回に絞る
• 通信の有無と返事の状態を読む
• 成功の返事を保存結果と照合する
• 待機、失敗、再試行の表示を確かめる

演習：一件の追加を、画面から保存先まで追う

練習用の読書メモ一件について、通信の道と失敗時の表示を調べます。APIをまだ使っていない場合は、その事実を図に書き、通信を使う版の期待する往復を設計します。

• 追加ボタンから保存までの図を描き、通信する場所にメソッドとURLを書く。
• 正常な入力、空の入力、通信が使えない状態で、期待する表示を決める。
• 成功という返事だけでなく、保存された内容を再取得する確認を一つ用意する。
• 二度押しや返事が届かない場合に、重複を増やさない再試行の手順を書く。

この回で確かめること

• 追加ボタンから保存までの図を描き、通信する場所にメソッドとURLを書く。
• 正常な入力、空の入力、通信が使えない状態で、期待する表示を決める。
• 成功という返事だけでなく、保存された内容を再取得する確認を一つ用意する。
• 二度押しや返事が届かない場合に、重複を増やさない再試行の手順を書く。

次の回：データは、どこに残るのか

参考資料

• CORS MDN: Cross-Origin Resource Sharing
• FETCH MDN: Using the Fetch API
• HTTP MDN: Overview of HTTP
• HTTP_STATUS MDN: HTTP response status codes