前回の続き——契約を「どんな流儀で」設計するか
前回のK-02では、エンドポイントとAPI契約を学びました。URL・メソッド・入力・出力・エラー・認証方式の6要素を、合意事項として先に決めるという話でした。ではその契約を、どんな規則で組み立てればよいのでしょうか。この講義で扱うRESTは、まさにその設計の流儀です。とくにURLとメソッドの決め方に、一貫した指針を与えてくれます。
このスライドのポイント
- K-02: エンドポイントとAPI契約の6要素を先に決める、を学んだ
- 今回の問い: その契約を、どんな規則で組み立てればよいか
- RESTは、とくにURLとメソッドの決め方に一貫した指針を与える設計の流儀
定義——リソースをURLで表し、メソッドで操作する
RESTとは、Web APIを設計するときの代表的な流儀です。その中心にあるのがリソースという考え方で、これは操作の対象になるデータのまとまりを指します。経費やユーザーなどが、一つひとつのリソースです。RESTの原則はシンプルで、リソースはURLで表し、その慣例として名詞の複数形を使います。そして、そのリソースをどう操作するかは、HTTPメソッドで表します。D-05で予告した「URLは名詞、メソッドは動詞」という考え方の、正式な姿がこれです。
このスライドのポイント
- REST＝Web APIの代表的な設計流儀
- リソース＝操作対象になるデータのまとまり（経費、ユーザー等）
- 原則1: リソースはURLで表す（名詞・複数形が慣例）
- 原則2: 操作はHTTPメソッド（D-05）で表す
- D-05で予告した「URLは名詞・メソッドは動詞」の正式版
なぜ必要か——設計の乱れを見抜けるようになる
RESTを知らないと、まずAIが生成したAPI設計の良し悪しを判断できません。たとえば /getExpenseData のように、URLの中に「get」という動詞が入り込んだ設計を見ても、それが乱れのサインだと気づけないのです。原則を持っていれば、この一貫性のなさをすぐ見抜けます。さらに、世の中の外部APIの多くはRESTに沿って作られているため、原則を知らないと、相手のドキュメントを読むのにも苦労します。
このスライドのポイント
- 知らないと: AIが生成したAPI設計の良し悪しを判断できない
- 例:
/getExpenseDataのような動詞入りURLの乱れに気づけない - 外部APIのドキュメントも読みにくくなる
構造——リソース×メソッドのマトリクス
RESTの構造は、リソースとメソッドのかけ合わせの表として整理できます。たとえば経費の集合を表す /api/expenses に対しては、GETで一覧を取得し、POSTで新規作成します。個別の経費を表す /api/expenses/7 に対しては、GETで1件を取得し、PATCHで一部を更新し、DELETEで削除します。ポイントは、URLは操作の対象を指すだけで、何をするかはメソッドが担う点です。D-05で見たメソッドの表が、ここでRESTの言葉として再登場しています。
このスライドのポイント
- 同じURLでも、メソッドで操作が変わる
具体例——悪い設計と良い設計の対比
具体的に、悪い例と良い例を並べてみます。悪い例は /createExpense や /deleteExpense2 です。URLの中に「create」「delete」という動詞が入り、しかも操作ごとに別々のURLが増えていきます。良い例では、作成は POST /api/expenses、2番の削除は DELETE /api/expenses/2 と表します。URLはあくまで経費というリソースを指すだけで、操作はメソッドが担います。URLに動詞が入り始めたら、設計が乱れ始めたサインだと覚えておいてください。
このスライドのポイント
- 悪い例:
/createExpense、/deleteExpense2（URLに動詞、操作ごとにURLが増える） - 良い例:
POST /api/expenses、DELETE /api/expenses/2 - URLに動詞が入り始めたら、設計が乱れ始めたサイン
技術サンプルカード——経費リソースのREST設計
サンプルは、経費というリソースをRESTで設計したときの一覧です。URLは /api/expenses と、個別を指す /api/expenses/7 の2種類だけで、あとはメソッドを切り替えて操作を表しています。ここで注目してほしいのは、規則が一貫していることの価値です。この並びを見た人は、たとえ初めて触るAPIでも「7番を消すなら DELETE を /api/expenses/7 に送ればよい」と推測できます。この推測が効くことこそ、RESTの一番のうまみです。
混同しやすい概念——RESTとHTTP
混同しやすいのが、RESTとHTTPの関係です。HTTPは、D章で学んだとおり、データをやり取りするための通信の規約そのものです。一方でRESTは、そのHTTPを前提として「URLとメソッドをどう決めるか」を指し示す設計の方針です。つまり、通信の土台であるHTTPの上に、設計の流儀であるRESTが乗っている、という関係になります。両者は別の層の話なので、混ぜて考えないようにしてください。
バイブコーディングでの確認点
バイブコーディングでの確認点です。AIにAPIの設計を頼むときは、指示に「RESTの原則で、リソースは複数形で」と一言添えてください。たったこれだけで、返ってくる設計の命名の一貫性が大きく上がります。そして生成された後は、URLに動詞が混じっていないか、同じリソースが別々のURLに散らばっていないかを、自分で点検します。AIへの質問例は「このAPI設計はRESTの原則に沿っていますか。動詞入りURLや一貫性のない箇所を指摘してください」です。
このスライドのポイント
- AIにAPI設計を頼むとき「RESTの原則で、リソースは複数形で」と一言添える
- それだけで命名の一貫性が大きく上がる
- 生成後は、動詞入りURLや同じリソースの散らばりを自分で点検する
一問一答とまとめ
最後に一問一答です。RESTでURLに入れるのは、名詞と動詞のどちらでしょうか。（間）答えは名詞です。動詞にあたる操作は、メソッドで表します。30秒でまとめます。RESTはWeb APIの設計の流儀で、リソースをURLの名詞で表し、操作をHTTPメソッドで表す、これが背骨です。この一貫性が、読みやすく推測しやすいAPIを生みます。次回のK-04では、そのAPIでやり取りされるデータの形、JSONとシリアライズへ進みます。関連資料は「API連携 超入門」と「API連携ワード100」です。
このスライドのポイント
- 一問一答: RESTでURLに入れるのは、名詞と動詞のどちら？
- 30秒まとめ: リソースはURLの名詞、操作はメソッドの動詞
- 次回: K-04 JSONとシリアライズ
- 関連資料: 「API連携 超入門」「API連携ワード100」
