Part 3 Webアプリケーション開発・動画
第11章 APIで画面と業務をつなぐ
動画台本ナレーション全文
Slide 01. バックエンドとAPI
第11章では、第9章のユースケースと第10章のデータ設計を、画面から呼び出せるAPIとして整理します。まずは、画面がバックエンドに何をお願いし、何を返してもらうのかを決めます。支援ステータス機能で、入力検証、認可、エラー、curl確認まで順番に見ます。
Slide 02. この章で持ち帰ること
この章で作るのは、API契約、認可の確認、処理の流れ、curl確認ログです。ユースケースからendpointを決め、入力と出力を約束として書き、誰が何をしてよいかを確認します。最後にHTTPのrequestとresponseで、書いた通りに動くか確かめます。
Slide 03. これまでをつなげる
第7章ではHTTP通信を観察しました。第8章ではAPI周辺の既存コードを読みました。第9章ではユースケースを整理し、第10章では支援ステータスを保存するデータ構造を設計しました。第11章では、それらをバックエンドAPIにしていきます。
Slide 04. APIは呼び出し方の約束
APIは、画面や他のプログラムがバックエンドを使うための、呼び出し方の約束です。URL、メソッド、送る情報、返す情報、成功や失敗の合図を決めると、呼び出す側と作る側が同じ前提で進められます。
Slide 05. DBとAPIの境界
APIは、DBを画面から直接触らせないための入口でもあります。第10章のテーブル設計はAPIの裏側にありますが、呼び出し元にテーブル構造をそのまま見せる必要はありません。画面が必要とする操作に合わせて公開します。
Slide 06. ユースケースからendpointへ
支援ステータス機能では、メンターが担当受講者一覧を見る、支援ステータスで絞り込む、担当受講者の支援ステータスを変更する、という操作があります。この操作ごとに、どのendpoint、つまりAPIの入口を用意するかを考えます。
Slide 07. CRUDとの違い
CRUDは、登録、取得、更新、削除の基本操作です。テーブル名だけでCRUDのAPIを作ると、誰が操作してよいか、どの業務ルールを守るかが隠れます。ここでは、メンターが担当受講者の支援ステータスを更新する操作として設計します。
Slide 08. HTTP methodを見る
HTTP method、つまりGETやPOSTの種類は、何をしたいかを表します。GETは取得、POSTは作成や実行、PATCHは部分更新、DELETEは削除に使うことが多いです。メソッドを選ぶと、APIを読む人が操作の意図を理解しやすくなります。
Slide 09. status codeを見る
status codeは、HTTPで処理結果を伝える数字の合図です。200系は成功、400系は入力や呼び出し方を見直す手がかり、500系はサーバー側で調べる手がかりです。失敗時も合図をそろえると、画面やデバッグで扱いやすくなります。
Slide 10. API契約を書く
API契約には、まずendpoint、method、目的、誰が呼べるかを書きます。次に、送る情報、返す情報、失敗したときの返し方、確認用curlを足します。実装前に揃えると、画面、テスト、レビューが進めやすくなります。
Slide 11. requestを分ける
requestは、URLの一部であるpath params、クエスチョンマークの後ろに置くquery params、追加情報のheaders、本文のbodyに分けます。learnerIdはpath、絞り込み条件はquery、更新したいstatusとnoteはbody、ログイン情報はheadersやセッションから扱います。
Slide 12. responseを設計する
responseは、画面が使いやすい形を意識します。DBの内部構造をそのまま返すより、learnerId、supportStatus、supportNote、updatedAtのように、画面でそのまま扱いやすい名前とまとまりで返します。
Slide 13. 入力検証を見る
APIは外から来る値をそのまま信じず、入口で検証します。learnerIdの形式、statusに入れてよい値、noteの長さ、必須か任意かを確認します。型や形式の検証と、業務ルールの確認を分けると整理しやすくなります。
Slide 14. 業務ルールを確認する
statusが正しい値でも、そのメンターが対象受講者を担当しているかは別の確認です。担当関係は業務ルールであり、同時に、この操作をしてよいかという認可の判断にも使います。API側で確認してから更新します。
Slide 15. 認証と認可
認証は、この呼び出しが誰から来たのかを確認することです。認可は、その人がこの操作をしてよいかを確認することです。ログイン済みであることと、対象受講者を変更できることは、分けて確認します。
Slide 16. mentorIdはサーバー側で決める
request bodyにmentorIdが入っていても、現在のメンターはログイン状態やセッションから取得します。呼び出し元が送った値をそのまま使うのではなく、バックエンド側で確認したユーザーを基準にします。
Slide 17. handlerに全部書かない
routeやhandlerは、HTTP requestを受け取り、responseへ変換する入口の関数です。入力検証、業務処理、DBアクセス、エラー変換を一つの関数に詰め込むと、どこを直せばよいか分かりにくくなります。役割を分けると、レビューでも流れを追いやすくなります。
Slide 18. use caseとrepository
use caseは、担当受講者かどうかなどの業務判断を置く場所です。repositoryは、DBの読み書きを担当する部品です。HTTPの都合、業務ルール、DBアクセスを分けると、小さな修正でも確認する場所を絞りやすくなります。
Slide 19. DB制約とAPIエラー
DB制約違反や対象データが見つからなかった場合は、APIのerror responseへ変換します。外部キー違反、CHECK違反、対象なしを、そのまま内部エラーにせず、呼び出し元が扱えるstatus codeとエラーcodeにします。
Slide 20. トランザクション
支援ステータス更新と履歴追加を同時に行う場合、片方だけ成功すると困ります。複数の更新をひとまとまりにしたいときは、トランザクションを使い、まとめて成功させるか、まとめて失敗させます。
Slide 21. error response
error responseには、開発者向けの目印であるcodeと、利用者に伝えるmessageを分けて入れます。入力エラーでは、どの項目がなぜエラーなのかも返します。stack traceのような内部情報や秘密情報はresponseに出しません。
Slide 22. curlで確認する
curlは、ターミナルからAPIを呼び出して確認するコマンドです。画面が完成する前でも、認証情報、Content-Type、request bodyを指定して、status codeとresponse bodyを見られます。必要に応じてDBの状態やログも確認します。
Slide 23. 異常系も確認する
確認ログでは、成功した場合だけでなく、入力不正、未ログイン、権限なし、対象なしも見ます。400、401、403、404、422のような失敗時のふるまいを、期待した結果、実際の結果、次に直すこととして記録します。そうすると、テストやPR確認につなげやすくなります。
Slide 24. AIにAPI案を頼む
AIには、endpoint案、requestとresponse案、error case、curl例の初稿を出してもらえます。依頼するときは、第9章のユースケース、第10章のDB設計、担当受講者チェック、今回作らない範囲を渡します。実データや秘密情報は、必要なら伏せ字やサンプル値にします。
Slide 25. 検証責任は人が持つ
AIが出したAPI案は、既存の認証方式、権限の決まり、DB制約、チームのAPI規約と照合します。存在しないフレームワークAPIや古い書き方が混ざることもあります。採用する前に、実行結果や公式ドキュメントで確認します。
Slide 26. 個人開発にも使う
個人開発でも、画面からデータを読み書きするAPIが必要になります。予約、投稿、コメント、支払いなどテーマが変わっても、API契約、入力検証、認可、確認ログの考え方は同じです。簡単でよいので残すと、後で説明しやすくなります。
Slide 27. 演習1 endpoint設計
演習1では、支援ステータス機能のユースケースからendpoint、つまりAPIの入口を設計します。一覧取得、絞り込み、更新に分け、method、目的、誰が呼べるかを書きます。テーブル名そのままのCRUDに寄りすぎていないかも確認します。
Slide 28. 演習2と3 契約と検証
演習2ではrequestとresponse、つまり送る情報と返す情報を書きます。演習3では、入力検証と認可を設計します。learnerId、status、noteの検証と、ログイン中のメンターが担当受講者を操作しているかの確認を分けます。
Slide 29. 演習4と5 流れと確認
演習4では、route、handler、use case、repository、DBの処理の流れを書きます。演習5では、curlでAPI確認ログを書きます。API契約、処理の流れ、確認ログは、第12章の画面要件と第13章のテスト設計の材料になります。