「APIってJSON返すやつでしょ」と若手に言われ、頷いていいのか迷ったことはないでしょうか。受託開発の現場で、設計レビューに出てくるエンドポイントの粒度がバラバラだったり、ステータスコードを 200 一本で返してきたり、認証の話をすると急に黙ってしまったり。指導している側からすれば「どこから説明すれば伝わるのか」が見えず、結局ベテランが書き直して終わる、という光景は珍しくありません。
この記事では、受託開発のシニア・リーダーが若手に API を教えるときに、Web の仕組み → HTTP → API の順で段階を踏ませる「3段階指導フロー」を整理します。なぜ若手の理解が止まるのかという原因の見立てと、各段階で押さえる観点、よくある失敗、そして指導者自身が体系を取り戻すための学びの導線まで扱います。
なぜ「APIってJSON返すやつでしょ」で止まるのか
若手が API でつまずくとき、本人の頭の中で何が起きているのかを言語化しておく必要があります。指導の打ち手は、原因の見立てがずれていると効きません。
現場でよく観察される止まり方は、おおむね次の3つに分けられます。
- 層の認識が曖昧：HTTP・API・Web アプリ・ブラウザの境目がぼやけ、すべて「Web のなにか」で一括りになっている
- 粒度の判断軸がない：1つのエンドポイントに複数の責務を詰める、逆に細かく分割しすぎる、の両方が同じ人の中で起きる
- 失敗系の引き出しが空：正常系の図は描けても、404 と 400 と 500 を分けて設計する発想がそもそもない
この3つは、いずれも「API という上位概念から教えてしまった」ことに原因があります。API はそれ自体が独立した技術ではなく、HTTP というプロトコルの上に「アプリ間でやり取りするための窓口」という意味づけが乗ったものです。下の層を素通りして API の話を始めると、若手は記号としてのキーワード（GET、POST、JSON、トークン）だけを覚えてしまいます。
ここを飛ばすと、設計レビューで「なぜこの粒度なのか」「なぜこのステータスコードなのか」と問われたときに、本人にも答えられなくなります。粒度や認証の判断は、HTTP の仕組みが判断の基礎になるからです。
3段階指導フロー：Webの仕組み → HTTP → API
指導の順序を、3段階で組み直します。1日で全部やろうとせず、それぞれの段階で本人に説明させる時間を取るのがポイントです。
第1段階：Webの仕組みを「やり取り」として描かせる
最初に伝えるのは、API ではなく Web 全体の構図です。ブラウザ・サーバー・データベースが、何をどの順で受け渡しているかを、若手に図で描かせます。
このとき、技術用語を先に与えないことが大事です。レストランの注文に例える、宅配便のやり取りに例える、といった「身近なやり取り」に置き換えてから、「いまの注文票が HTTP リクエストにあたる」と後付けで紐づけます。
確認する観点は3つだけで構いません。
- リクエストとレスポンスは必ず一対であること
- リクエストを送るのはクライアント側で、返すのはサーバー側であること
- 一回のやり取りは独立しており、サーバー側は前回の状態を覚えていないこと（だからセッションや Cookie が必要になる、と後の段階につながる）
ここで本人が図を描けない場合、API の話に進んでも無駄です。手戻りを覚悟して、もう一度この段階に戻します。
第2段階：HTTPの「どう伝えるか」を分解する
次に、リクエスト1本の中身を分解します。URL、メソッド、ヘッダー、ボディ、ステータスコードのそれぞれが「何を伝えるためのもの」なのかを言わせていきます。
ここで重要なのは、ステータスコードの役割を正常系と異常系の両方で説明させることです。多くの若手は 200 と 404 しか口にしません。指導側からは、次のような問いを投げます。
- 認証が通っていないときは何番で返すか、なぜ 404 ではダメなのか
- クライアントの入力が不正なときと、サーバー側が壊れているときで、なぜ番台を分けるのか
- リダイレクトが必要な場面はどんなときか、それを 200 で返すと何が起きるか
この問いに自分の言葉で答えられたら、第2段階は通過です。逆に「とりあえず 200 を返しておけば動くから」と言うようなら、まだ HTTP を「動かすための呪文」として扱っている段階だと判断できます。
第3段階：APIを「窓口の設計」として教える
ここでようやく API の話に入ります。API を教えるときの軸は、「何を、どの粒度で、どんなルールで公開するか」の3点です。
粒度の判断軸は、リソース指向で考える練習から始めるのが現実的です。「ユーザー情報を取得する」を /users/{id} と書くか、/getUserInfo と書くか、という比較を実際にさせると、HTTP のメソッドとパスの役割分担が腹落ちします。
認証は、最初から OAuth や JWT の細部に入らないようにします。順序としては、
- なぜそもそも認証が必要なのか（公開してよい情報と、そうでない情報の線引き）
- リクエストの中で「誰からのリクエストか」をどう伝えるか（ヘッダーで渡す）
- その情報をどう発行・失効させるか（トークンの寿命管理）
の3層に分けて、上から順に説明させます。いきなり Bearer トークンの実装から入ると、なぜトークンが必要かを説明できないまま実装する若手が育ってしまいます。
指導でよくある失敗
3段階指導を導入しても、リーダー側のやり方次第で空回りします。現場で観察される失敗パターンを挙げておきます。
失敗1：用語の網羅から入ってしまう HTTP・API の用語一覧を渡し、「全部覚えてから設計レビューに出てきて」と言ってしまうケースです。網羅型の学習は、若手にとって意味の優先順位がつかない学び方になりがちです。3段階フローは、用語ではなく「やり取り」「分解」「設計」という思考の階段を登らせる設計だと意識してください。
失敗2：正常系の図しか描かせない 「正常に動く API を1本作らせる」だけで指導を終えると、ステータスコードの設計感覚が育ちません。最初から、認証エラー・入力エラー・サーバーエラーをそれぞれ返すケースをセットで考えさせると効果的です。
失敗3：レビューで結論だけ伝える 「ここは 400 じゃなくて 422 にして」と修正指示だけ伝えると、本人は次回も判断できません。なぜそう判断したかの根拠を、HTTP の意味から説明する癖を、指導側がまず持つ必要があります。
失敗4：教える側の体系が古いまま シニア側も、Cookie・セッションの扱いや CORS、認可の最近の流儀を改めて整理しないままだと、若手の質問に「昔こうだった」で答えてしまいます。指導フローを敷くのと同時に、自分の知識を一度整理し直す機会を持つことを勧めます。
指導者として体系を取り直すために
ここまでのフローを実際に運用すると、多くのリーダーが直面するのが「自分の説明の語彙が、ところどころ抜けている」という気づきです。長く受託の現場にいる人ほど、API の使い方は手に染み付いているものの、HTTP の仕様レベルで体系的に説明することからは離れているケースがあります。
若手に教える順序を整える前に、一度自分の中の Web 通信の体系を組み立て直すと、指導の解像度が一気に上がります。リクエスト/レスポンスの基本、URL とクエリパラメータ、ステータスコードの番台ごとの役割、API の窓口設計、Cookie とセッションの仕組みまでを、同じ語り口で順序立てて学べる入口を持っておくと、若手への説明にもそのまま転用できます。
このテーマを身近なたとえで段階的に整理した教材として、Webの仕組み入門講座（HTTP・API・通信の基本を体験で学ぶ）を見る が役立ちます。指導者自身が一度受講して指導の語彙を揃えるのも、若手本人の自学に勧めるのも、どちらの使い方も自然です。要件定義の読み解きまで踏み込ませたい場合は、続けて要件定義の読み方入門講座につなげると、Web の仕組みと業務要件の両面からアプローチできるようになります。
なお、若手育成全般のつまずきや、指導役のレビュー姿勢については、指示待ち部下を動かすAIアサイン・マネジメントプロンプト術 や プログラミングの挫折を防ぐAIメンター育成プロンプト術 でも具体的な進め方を扱っています。技術指導と育成設計はどうしても重なる領域なので、合わせて参考にしてください。
まとめ：教える順序を整えるだけで、レビューの質が変わる
API が伝わらない若手に、API から教え直しても効きません。Web 全体の「やり取り」を描けるようにし、HTTP の中身を分解させ、その上で API という窓口の設計に入る。この3段階の順序を踏ませることで、設計レビューでの粒度のばらつきや、ステータスコード・認証の浅い理解は、確実に減っていきます。
指導フローを定着させるために、明日から始められる一歩を3つだけ挙げておきます。
- 次の若手レビューで、API の話に入る前に「Web のやり取りの図」を描かせてみる
- 設計指摘のときに、結論だけでなく「なぜその HTTP の挙動からその粒度になるか」をセットで言葉にする
- 指導者自身が Web 通信の体系を一度整理し直し、語彙を揃える
指導は「教えれば伝わる」ものではなく、「教える順序を組み直すと伝わるようになる」ものです。3段階フローを、まずはチームの中で1人の若手に試してみてください。
関連講座
- Webの仕組み入門講座を見る （本記事で扱った Web の仕組み → HTTP → API の3段階を、身近なたとえで体系化した教材。指導者の整理にも、若手の自学にも使えます。）
- 要件定義の読み方入門講座を見る （Web 通信の理解の次に、要件定義側の読み解きまで踏み込ませたい場合に。）