AI全盛の今だからこそ、あえてもう一度振り返るAPIの基礎

2026/05/19（火）に開催された「Postman API Night Nagoya 2026 Spring」における私の発表「AI全盛の今だからこそ、あえてもう一度振り返るAPIの基礎」の発表資料になります。

https://postman.connpass.com/event/385101/

#APINight

Transcript

1. AI全盛の今だからこそ、あえてもう一度 振り返るAPIの基礎 2026.05.19 Postman API Night Nagoya 2026 Spring KDDIアジャイル開発センター 名古屋オフィス 鈴木 正樹
2. 1 KDDI Agile Development Center Corporation 自己紹介 ◼ 氏名：鈴木 正樹 ◼ 所属：KDDIアジャイル開発センター（KAG） 名古屋オフィス ◼ 役割：クラウドアーキテクト ＆ Atlassian テクニカルエキスパート サーバーレス＆IaCが大好き。好きなサービスはAWS LambdaとAWS CDK 主にJAWS-UG CDK支部 & JAWS-UG 名古屋で活動 ◼ Certification： ◼ AWS Community Builder(serverless)（2023～） ◼ Scrum Inc. 認定スクラムマスター（2025～） ◼ : @makky12（SUZUKI Masaki@クラウドエンジニア） ◼ Blog：https://makky12.hatenablog.com/
3. 2 KDDI Agile Development Center Corporation この発表について • 生成AI全盛のこの時代、コーディングはほとんど生成AIが行ってくれるようになり、自分で API(REST API)のコードを実装することも少なくなりました • しかしその結果、REST APIについて「聞いたことはあるが、詳細は良く知らない」という方も いるのではないでしょうか？ • そこでこの発表では、いま一度「APIの基礎」そして「最低限必要な知識」に触れるとともに、 先日Xで話題になった「あの話題」についても少し触れようと思います
4. 3 KDDI Agile Development Center Corporation アジェンダ • Web APIの基礎（REST/メソッド/リクエスト・レスポンス） • セキュリティ上の制約（SOP/CORS/プリフライトリクエスト） • Tips：「POSTメソッドでデータ取得を行ってはいけないのか？」 • まとめ ※ この資料は、下記URLで公開済みです ◦ この資料です
5. 4 KDDI Agile Development Center Corporation Web APIの基礎（REST/メソッド/リクエスト・ レスポンス）
6. 5 KDDI Agile Development Center Corporation 「Web API」とは？ API (Application Programming Interface) • アプリケーションやソフトウェア同士がデータ・機能をやり取りするための仕組みの一つ Web API • フロントエンドとバックエンドがhttp(s)を使い、データをやり取りする仕組み 例）レストランでの注文に例えると… サーバー データベース・ ストレージなど Web API クライアント Webサービスではフロントエンドとバックエンドがやり取りするための窓口が必要 様々な実装 リクエスト レスポンス
7. 6 KDDI Agile Development Center Corporation REST API REST API （REpresentational State Transfer API） • サービスの呼び出しを「リソース」への操作に見立てて実行する（多くの公開APIのベースになっている） • 「リソース指向アーキテクチャ」であり、リソース（=扱うデータ）に直感的な名前をつけて公開する ◦ リソースを識別する名前（URI）は、構造的で予想しやすい名前が良い • 「操作を『HTTPメソッド』で指示する」「実行する側＆される側の情報をオブジェクトでやりとりする」etc. /users /payment /map/35.700,139.747
8. 7 KDDI Agile Development Center Corporation REST APIで使用するHTTPメソッド • REST APIで使用する主なHTTPメソッドとして、以下の4つがあります。 ◦ 実際はすべてのHTTPメソッドを使用可能ですが、実際よく使われるのは以下の4つ（中でもGetとPost）です メソッド 説明 対応するCRUD 備考 Get（取得） 指定したURLのリソース（データ）を 読み込む R（Reference） ・クエリパラメータ/pathパラメータで データをやり取りすることが多い（可視 性が高い） Post（作成） 新しいリソースを作成する C（Create） ・bodyパラメータでデータをやり取り することが多い（可視性が高くない） Put（更新） 既存のリソースを書き換える U（Update） ・同上 Delete（削除） リソースを削除する D（Delete） ・同上
9. 8 KDDI Agile Development Center Corporation REST APIでのデータのやり取り • REST APIでは、データのやり取りにオブジェクト（リクエストオブジェクト/レスポンスオブ ジェクト）が用いられる（プログラム言語においては、一般的にJSON形式が用いられる） • 赤は基本情報（URI/メソッド/ステータスコード）、オレンジはヘッダー情報(Content-Type やAuthorizationなど)、緑はボディ(その他やり取りする情報)と呼ばれる部分。 リクエストオブジェクト レスポンスオブジェクト
10. 9 KDDI Agile Development Center Corporation セキュリティ上の制約（SOP/CORS/プリフライ トリクエスト）
11. 10 KDDI Agile Development Center Corporation SOP（同一オリジンポリシー：Same-Origin Policy）について • SOPとは「オリジン（※）が違うリソースへのアクセス」を制限するブラウザのセキュリ ティ制約 ◦ 具体的には「アクセスした結果を取得できない」という現象が発生する（アクセス自体は行われる） ◦ この制約に引っかかった場合、下記エラーメッセージがブラウザのコンソールに表示されます • この「アクセス」には、もちろん「REST APIのリクエスト」も含まれます • SOPに引っかかると、例えば以下の処理が実行できない ◦ あるアプリケーションから別アプリケーションで公開されているAPIを実行する（例：各種SNSなど） ◦ 開発中にローカル環境（http://localhostなど）から開発環境のWeb API（API Gatewayなど）にアクセスする • おそらく、SOPに一番悩まされるのはこの状況 ※ URLの「プロトコル + ホスト + ドメイン + ポート番号」までの部分の事（ただしプロトコルはほぼhttpsで固定、 ポート番号は省略されることがほとんどなので、実質「FQDN（完全修飾ドメイン名）と同様」と考えてよい） Access to XMLHttpRequest at <アクセス先オリジン> from origin <アクセス元オリジン> has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource
12. 11 KDDI Agile Development Center Corporation CORS（オリジン間リソース共有）について ※CORS: Cross-Origin Resource Sharing の略 • CORSとは「異なるオリジンのリソースへのアクセス」を許可するブラウザの仕組み ◦ アプリケーション的にはSOPがあると色々不便な点も多いため、それを緩和するための仕組み • サーバーサイド側では、下記3つのレスポンスヘッダーを設定することで対応可能 ◦ Access-Control-Allow-Origin：許可するオリジンを指定 ◦ Access-Control-Allow-Headers：許可するリクエストヘッダーを指定（「Content-Type」など） ◦ Access-Control-Allow-Methods：許可するメソッドを指定（GET, POSTなど） ◦ 全部許可する場合は「*」を指定 • その他「プリフライトリクエスト（OPTIONメソッド）」を受け取れるように設定する必要がある（次頁で説明）
13. 12 KDDI Agile Development Center Corporation 「シンプルリクエスト」と「プリフライトリクエスト」 ※ちなみに「プリフライト（preflight）」とは、航空機の離陸前に行う安全確認の事です 下記を全て満たす場合「シンプルリクエスト」となり、直接REST APIリクエストを実行する ◦ HTTPメソッドが「GET」「POST」「HEAD」のいずれかである ◦ 標準的なヘッダー（「Accept」「Accept-Language」「Content-Type」等）のみ利用している ◦ Content-Typeヘッダの値が「application/x-www-form-urlencoded」「multipart/form-data」 「text/plain」 のいずれか（通常「application/json」を使うREST APIは「シンプルリクエスト」ではない） • 上記を満たさない場合「プリフライトリクエスト」となり、 OPTIONメソッドを使用したプ リフライト（=事前確認）リクエストを送信する ◦ サーバーがプリフライトリクエストに対して許可を返した場合のみ、本来のREST APIリクエストを送信する • サーバー側でも、このOPTIONメソッドによるプリフライトリクエストを受け取れるように 設定する必要がある（これがCORS対応でハマりやすい部分）
14. 13 KDDI Agile Development Center Corporation Tips：POSTメソッドでデータ取得を行っては いけないのか？
15. 14 KDDI Agile Development Center Corporation Tips：POSTメソッドでデータ取得を行ってはいけないのか？ • 少し前にXで下記ポストをきっかけに「POSTでデータ取得するな」「別に問題ないだろ」と 論争が起こったのを覚えている（ご存じ）でしょうか？ • この論争では色々な意見が出ましたが、実際のREST APIの規約としてはどうでしょうか？
16. 15 KDDI Agile Development Center Corporation 個人的な意見：いけないことはないが、可能ならメソッドに従った方が良い • REST APIでは、仕組みとして「HTTPメソッド」を用いて各種処理を行う • ただしあくまで「HTTPメソッドを介して各種処理を行う」というだけで「絶対に処理に対応 したメソッドを使わないといけない」という事ではない（そのような規定はない） ◦ そのため「POSTメソッドでデータ取得を行ってはいけない」なんて事はない • とはいえ「HTTPメソッドを介する」以上、特に理由なくメソッドと処理が一致していないと いうのは分かりにくいのは確か（剣道で「面！」と言って胴を決めるような感じ？） • 個人的には「基本はREST APIの仕組みに沿う」「ただし、何か正当な理由がある場合はその 限りではない」という運用が良いと思う
17. 16 KDDI Agile Development Center Corporation 参考情報：「X-HTTP-Method-Override」ヘッダについて • 「X-HTTP-Method-Override」ヘッダにメソッドを指定することで、メソッドの内容を上書 きできる（例：POSTメソッドで送られたリクエストでデータ取得処理を行うなど） • ただし、あくまで「昔からの慣習的なもの」という側面が強く、近年はこれを使用せず「実 行するHTTPメソッドを直接指定する」のが主流のため、過信しないこと（必要に応じてサー バー側で対応する処理を実装することが必要） • 現在はどちらかといえば、運用時に「リクエストではXXXメソッドが送られるけど、実際に 行う処理はYYYだよ」という事を関係者に認識させる側面の方が強いかも
18. 17 KDDI Agile Development Center Corporation まとめ
19. 18 KDDI Agile Development Center Corporation まとめ ※ 本セッションのまとめ • REST APIとは「アプリケーションやソフトウェア同士がデータ・機能をやり取りするための 仕組みの一つ」である ◦ 「リソースベース」で、URI、HTTPメソッドなどを用いhttp(s)でリクエスト/レスポンスを実行する • SOP/CORS/プリフライトリクエストなど、セキュリティ上の規約に注意する ◦ 意図せずREST APIリクエストがブロックされることがあるので注意（特にWebフロントからのリクエスト） • 「メソッドと実際の処理が違ってはいけない」ことはないが、基本は同じにした方が良い ◦ 「何か理由がある場合」のみにしておき、基本はREST APIの仕組みに合わせたほうが分かりやすい ◦ 「X-HTTP-Method-Override」ヘッダを使い、コードベースで関係者に認識させるという方法もある
20. Be a Change Leader. アジャイルに力を与え 共に成長し続ける社会を創る