AIエージェントに社内システムを触らせる前に読むWeb API設計の本｜命名・冪等性・エラー設計を固める4冊

「社内システムをAIエージェントに触らせたい」という相談が明らかに増えました。MCPサーバーを立てて既存のREST APIをそのままツールとして生やすところまでは、半日もあれば動きます。詰まるのはその後です。同じ登録処理を2回叩いて伝票が二重に立つ、一覧取得が全件を返してコンテキストを食い潰す、エラーなのにHTTPステータスが200なのでエージェントが成功と解釈して次へ進む。原因を追うとモデルではなく、叩かれる側のAPIの設計に行き着きます。この記事では、Web APIとインタフェース設計を学べる実在の日本語書籍を4冊、段階順に紹介します。なお本記事は書籍紹介であり広告を含みます。価格・版・在庫・目次は変わるため、最新は各出版社の公式ページでご確認ください。

エージェントが叩く相手は、UIではなくAPIです#

まず前提を揃えます。人間の担当者が社内システムを使うとき、目に入るのはAPIのレスポンスだけではありません。画面のラベル、隣の注意書き、押せないボタン、業務マニュアル、「この画面は月末だけ使う」という職場の暗黙知。これらが全部そろって操作が成立しています。

エージェントに見えるのはごく一部です。ツール定義の説明文、パラメータのスキーマ、返ってきたレスポンス本文。それだけで、画面のラベルも注意書きも押せないボタンも存在しません。

つまりエージェント導入は、これまでUIが吸収していた曖昧さをAPIの表面に露出させる作業でもあります。よくできたAPIはこの露出に耐えますが、耐えないAPIは、耐えないという事実が繋いだ日に初めて分かります。

エージェントに使わせたときだけ表に出る、APIの症状#

止まっているチームの症状は、だいたい次のどれかです。人間が使っている間は「慣れれば分かる」で通っていた種類の問題ばかりです。

• 名前から動作が読めない。/api/v2/proc や doAction のような名前だと説明文しか手がかりがなく、選択を外します
• 粒度が細かすぎる。1つの業務タスクに8回も10回も呼ばせる構成だと、途中で文脈が薄まり順序を間違えます
• 常に200 OKを返し、成否をボディの中の独自フィールドで表現している。エージェントは成功したと解釈して次へ進みます
• 冪等でない。通信が切れて再送した結果、伝票が二重に立ちます。エージェントは人間よりリトライしがちです
• ページングが曖昧。全件返る、あるいはoffset方式で、途中でデータが増減すると重複や取りこぼしが出ます
• 認可が画面側にある。「この人にはこのボタンを出さない」で制御していた場合、API直叩きでは何の防御にもなりません
• レスポンスが巨大。1件100フィールドのうちエージェントが使うのは3個、という状態でコンテキストを消費します

4段階で読む順番を決める#

API設計の本は同じ棚に並んでいても前提が違います。HTTPの語彙が共有できていないのか、1本のAPIの設計判断で迷っているのか、操作の形が揃わないのか、サービスをまたいだ契約の変更で壊れているのかで、必要な本が変わります。

以下、この順で4冊を紹介します。守備範囲は重なりますが、通読前提の並びではありません。症状から選ぶための対応表は記事末尾に置いてあります。

1. Webの語彙を揃える(Webを支える技術)#

1冊目は、HTTP、URI、HTML、そしてRESTというWebの基盤技術を解説する本です。山本陽平さんの著書で、技術評論社から2010年4月8日に刊行されました。WEB+DB PRESS plusシリーズの1冊で、A5判400ページです。公式の書誌ページでは、これらの仕様を歴史や設計思想を織り交ぜて解説し、望ましいURI、HTTPメソッドの使い分け、クライアントとサーバの役割分担、設計プロセスなどのベストプラクティスを紹介する、と説明されています。

構成は5部17章と付録です。第1部Web概論(Webとは何か、Webの歴史、REST)、第2部URI(URIの仕様、URIの設計)、第3部HTTP(HTTPの基本、HTTPメソッド、ステータスコード、HTTPヘッダ)、第4部ハイパーメディアフォーマット(HTML、microformats、Atom、AtomPub、JSON)、第5部Webサービスの設計(読み取り専用、書き込み可能、リソースの設計)。付録にステータスコード一覧とHTTPヘッダ一覧が付きます。

この本がいちばん効くのは第7章と第8章です。第7章「HTTPメソッド」の7.11「べき等性と安全性」には、PUTがべき等、DELETEもべき等、GETとHEADはべき等かつ安全、POSTは安全でもべき等でもない、という整理が置かれ、続く7.12「メソッドの誤用」ではGETが安全でなくなる例、PUTやDELETEがべき等でなくなる例が並びます。エージェントはタイムアウトや不明瞭なエラーを見ると再試行しがちで、そのとき安全に再送できるかは設計側が決めておくべき性質です。この2節は、開放するAPIの棚卸しにそのまま使えます。

この整理はHTTPの仕様そのものにも書かれています。RFC 9110の9.2.2「Idempotent Methods」は、同じリクエストを複数回送ったときのサーバへの意図された影響が1回送ったときと同じであれば冪等である、と定義し、PUT、DELETE、および安全なメソッドが冪等だとしたうえで、クライアントは冪等でないメソッドのリクエストを自動的に再試行すべきではない(SHOULD NOT)と述べています。エージェントを「行儀の悪いクライアント」だと思って読むと、この規定の重みが変わります。

第8章の8.5「ステータスコードとエラー処理」と8.6「ステータスコードの誤用」は、前述の「常に200 OKを返す」症状を扱う節です。エージェントは機械可読な信号があれば使いますが、無ければボディの文字列を読んで推測します。推測させる設計は、そのぶん外れます。

扱っていない範囲も書いておきます。刊行が2010年なので、HTTP/2以降、GraphQL、gRPC、OpenAPI、JWTを使った認可設計は範囲外です。第4部のmicroformatsやAtomPubも、現在のWeb API開発の中心的な話題とは言えません。それでもURI、HTTPメソッド、ステータスコード、ヘッダという層は当時から変わっておらず、語彙を揃える目的なら現在も機能します。この本を「最新のAPI開発の教科書」として読むのは目的違いです。

Webを支える技術 ―― HTTP、URI、HTML、そしてREST(技術評論社)

広告

著者: 山本陽平 / 出版社: 技術評論社(WEB+DB PRESS plus) / 2010年4月刊 / A5判400ページ。Web概論、URI、HTTP、ハイパーメディアフォーマット、Webサービスの設計の5部構成。べき等性と安全性、メソッドの誤用、ステータスコードとエラー処理の節が、開放するAPIの棚卸しに使えます。HTTP/2以降、GraphQL、gRPC、OpenAPI、JWTを使った認可設計は扱っていません。

Amazonで見る楽天で見るYahoo!ショッピングで見る

※価格・在庫は変動します。最新の情報は各販売サイトでご確認ください。

2. 1本のAPIの設計判断を型にする(Web API: The Good Parts)#

2冊目は、Web APIの設計・開発・運用を扱う実務書です。水野貴明さんの著書で、オライリー・ジャパンから2014年11月21日に刊行されました。224ページです。公式の書誌ページでは、「設計の美しいAPIは、使いやすい、変更しやすい、頑強である、恥ずかしくない」という考えのもと、APIをどう設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにする、と説明されています。対象は、URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなタイプのAPIです。

構成は全6章と付録2本。1章「Web APIとは何か」、2章「エンドポイントの設計とリクエストの形式」、3章「レスポンスデータの設計」、4章「HTTPの仕様を最大限利用する」、5章「設計変更をしやすいWeb APIを作る」、6章「堅牢なWeb APIを作る」で、付録Bには「Web APIチェックリスト」が付きます。

エージェント文脈で効く節を挙げます。2章には2.4.2「利用する単語に気をつける」、2.4.4「単語をつなげる必要がある場合はハイフンを利用する」といった命名の節があります。命名は人間相手でも重要ですが、ツール名と説明文だけを手がかりに選ぶエージェント相手では影響が一段大きくなります。

2.5「検索とクエリパラメータの設計」には、2.5.2「相対位置を利用する問題点」と2.5.3「絶対位置でデータを取得する」が並びます。offsetベースのページングがデータの増減で重複や取りこぼしを起こす問題を扱う箇所です。エージェントは一覧を舐めながら作業することが多く、途中で取りこぼしても「無いものは無い」と結論して次へ進みます。人間なら気づく違和感に、気づきません。

3.6「エラーの表現」も重要です。3.6.1「ステータスコードでエラーを表現する」から3.6.4「エラーの際にHTMLが返ることを防ぐ」までが並びます。最後の節は地味に効きます。認証切れやメンテナンス時にログイン画面のHTMLが返るAPIは珍しくなく、エージェントはそれを読んで意味不明な推論を始めます。

エラー形式については標準もあります。RFC 9457「Problem Details for HTTP APIs」(2023年7月発行、RFC 7807を廃止)は、機械可読なエラー詳細を伝える形式として、application/problem+json などのメディアタイプと、type、title、status、detail、instanceという中核のメンバを定義しています。typeがURIで問題の種類を識別し、detailがその発生に固有の説明を担う、という分担がそのまま「エージェントが次に何をすべきか」の材料になるため、自前の形式を毎回考えるより扱いが安定します。

6.6「大量アクセスへの対策」も、エージェント時代には位置づけが変わった節です。ユーザーごとの制限、レートリミットの単位、制限値を超えた場合の対応、その伝え方が並びます。従来これは外部公開APIの話でしたが、社内APIをエージェントに開放すると社内でも同じ問題が起きます。人間が1日に数回しか叩かなかった集計APIが、エージェント経由では短時間に何十回も呼ばれることがあります。

扱っていない範囲は、以降に一般化した技術です。刊行が2014年なので、GraphQL、gRPC、OpenAPI 3系、HTTP/2以降、MCPのようなプロトコル、RFC 9457のような後発の標準は範囲外で、サービス間の内部通信や分散トランザクションも主題ではありません。守備範囲は「1本の公開Web APIをどう設計して運用するか」に絞られており、そのぶん判断の解像度は高い一冊です。

Web API: The Good Parts(オライリー・ジャパン)

広告

著者: 水野貴明 / 出版社: オライリー・ジャパン / 2014年11月刊 / 224ページ。エンドポイント設計、レスポンスデータの設計、HTTPの仕様の利用、設計変更のしやすさ、堅牢性の全6章。命名、絶対位置でのページング、エラー表現、バージョニング、レートリミットを判断の理由つきで扱います。GraphQL、gRPC、OpenAPI 3系、HTTP/2以降、サービス間の内部通信は扱っていません。

Amazonで見る楽天で見るYahoo!ショッピングで見る

※価格・在庫は変動します。最新の情報は各販売サイトでご確認ください。

3. 操作の形をパターンとして持つ(APIデザイン・パターン)#

3冊目は、Web APIを構築するための設計原則とパターンを体系的にまとめた本です。JJ Geewaxさんの著書、松田晃一さんの訳で、マイナビ出版から2022年8月26日に刊行されました。Compass BooksシリーズのB5変判528ページ、原著は『API Design Patterns』です。公式の書誌ページでは、Google Cloud PlatformとそのAPI設計に取り組む著者が、APIの一貫性、拡張性、可用性を確保する方法や、安全かつ柔軟で再利用可能なAPIパターンを解説する、と説明されています。コード例はTypeScript。同ページの著者紹介によれば、GeewaxさんはGoogleのソフトウェアエンジニアで、GoogleではじまったAPI設計標準に関する業界全体のコラボレーションであるAIP.devの共同設立者です。

構成は6パート30章です。PART 1がAPI入門とAPIデザインパターン入門。PART 2「設計の原則」が名前付け、リソースの範囲と階層、データ型とデフォルト値。PART 3「基礎編」がリソース識別子、標準メソッド、部分的な更新と取り出し、カスタムメソッド、ロングランオペレーション、再実行可能ジョブ。PART 4「リソース間の関係」、PART 5「コレクションの操作」がバッチ操作、ページ分割、フィルタリングなど。PART 6「安心と安全」がバージョンと互換性、論理削除、リクエストの重複実行回避、リクエストの検証、リクエストの再試行、リクエストの認証です。

この目次は、エージェント実務の症状と素直に対応します。

とくに第26章「リクエストの重複実行回避」と第27章「リクエストの検証」は、繋ぐ前に読む価値があります。冪等でないPOSTを安全に再送させるには、クライアント側が生成した識別子をサーバが記録して重複を弾く仕組みが要ります。エージェント固有の発明ではなく、決済や在庫のAPIが昔からやってきたことです。検証も同じで、実行せずに検証だけ行うモードがAPI側にあれば、「まず確認してから実行する」という手順が設計として成立します。無ければ、その手順はプロンプトによるお願いに過ぎません。

第21章「ページ分割」に関連して、著者が共同設立者に名を連ねるAIP.devにも同じ主題の文書があります。AIP-158「Pagination」は、リクエストにpage_sizeとpage_token、レスポンスにnext_page_tokenを置く形を示し、ページトークンは利用者が解析できない不透明な(URLセーフな)文字列であるべきだとしています。また、既存のRPCへのページネーションの追加は後方互換性を破壊する、とも述べています。社内APIにページングを後付けするときの注意点そのものです。

扱っていない範囲は、HTTPの下回りと運用です。本書はパターン集であり、HTTPの仕様やURI設計の基礎は前提として扱われます。公式の書誌ページでも、JSONなどのシリアライゼーション・フォーマットや一般的なストレージ知識、HTTPとそのメソッドに精通していることが理解の助けとなる、と書かれています。1冊目や2冊目を飛ばして入ると背景が読み取りにくく、マイクロサービスの分割方針や運用・組織論は4冊目の担当です。

APIデザイン・パターン(マイナビ出版 Compass Booksシリーズ)

広告

著者: JJ Geewax / 訳: 松田晃一 / 出版社: マイナビ出版 / 2022年8月刊 / B5変判528ページ。原著は『API Design Patterns』。名前付け、標準メソッド、部分的な更新、ロングランオペレーション、ページ分割、フィルタリング、リクエストの重複実行回避、検証、再試行、認証を6パート30章で体系化します。コード例はTypeScript。HTTPやURIの基礎、マイクロサービスの運用・組織論は扱っていません。

Amazonで見る楽天で見るYahoo!ショッピングで見る

※価格・在庫は変動します。最新の情報は各販売サイトでご確認ください。

4. 分散の現実と、契約の進化に備える(マイクロサービスアーキテクチャ 第2版)#

4冊目は、マイクロサービスの仕組み、特徴、長所、短所、課題を技術面と組織面の両方から扱う本です。Sam Newmanさんの著書、佐藤直生さんの監訳、木下哲也さんの訳で、オライリー・ジャパンから2022年12月2日に刊行されました。664ページ、原著は『Building Microservices, 2nd Edition』です。公式の書誌ページでは、著者はマイクロサービスに賛成でも反対でもないという中立的な立場から解説しており、技術的側面のみならず組織面にも示唆を与える、と説明されています。

構成は3部16章です。第I部「基礎」がマイクロサービスとは、モデル化、モノリスの分割、通信スタイル。第II部「実装」が通信の実装、ワークフロー、ビルド、デプロイ、テスト、監視から可観測性へ、セキュリティ、レジリエンス、スケーリング。第III部「人」がUI、組織構造、進化的アーキテクトです。

「うちはマイクロサービスをやる予定はない」という方も、5章だけは読む価値があります。5.1「理想的な技術の探索」は、後方互換性を容易にする、インタフェースを明示的にする、APIを技術非依存にする、コンシューマにとって単純なサービスにする、内部実装の詳細を隠す、という5つの観点で構成されており、そのままエージェントに開放するAPIに求める性質のリストになります。とくに最後の1つは重要で、テーブル構造がそのまま漏れているAPIは、スキーマ変更のたびにエージェント側の挙動が変わります。

5.4「スキーマ」には5.4.1「契約の構造的破壊と意味的破壊」という節があります。フィールドを消したり型を変えたりする構造的な破壊はスキーマ検証で機械的に検知できますが、厄介なのはフィールド名も型も同じまま意味だけ変わる意味的な破壊です。人間の呼び出し側なら気づくことがありますが、エージェントは説明文に書かれた古い意味のまま呼び続けます。続く5.6「破壊的変更の回避」と5.7「破壊的変更の管理」は、拡張変更、耐性のあるリーダー、互換性のないバージョンの共存、旧インタフェースのエミュレーションといった選択肢を並べており、社内APIの変え方を決めるときの叩き台になります。

12章「レジリエンス」の12.5「安定性パターン」には、タイムアウト、再試行、バルクヘッド、サーキットブレーカー、冗長性、冪等性が並びます。エージェントは複数のツールを順に呼ぶため、1つのAPIが遅いだけで全体が止まります。

11章「セキュリティ」の11.6「認証認可」には、11.6.5「粒度の細かい認可」、11.6.6「混乱した代理問題」、11.6.7「一元的な上流での認可」といった節があります。混乱した代理問題は、エージェント経由の社内システム連携でまさに起きます。強い権限のサービスアカウントで動くエージェントは、依頼した人が本来触れないデータまで取れてしまうからです。新種の問題ではなく、古くから名前のついた問題だと分かります。

扱っていない範囲は、HTTP以下の詳細とAPI設計の細部です。本書はアーキテクチャと組織の本で、命名規約やページングの実装パターンは3冊目の担当です。664ページと分量もあり、モノリスで足りている組織が最初に読む本ではありません。読むべきは「サービスが複数に分かれていて契約の変更で壊れている」もしくは「これから分けるか判断したい」段階です。

マイクロサービスアーキテクチャ 第2版(オライリー・ジャパン)

広告

著者: Sam Newman / 監訳: 佐藤直生 / 訳: 木下哲也 / 出版社: オライリー・ジャパン / 2022年12月刊 / 664ページ。原著は『Building Microservices, 2nd Edition』。基礎・実装・人の3部16章で、通信、スキーマと契約の破壊的変更、ワークフローとサーガ、可観測性、セキュリティ、レジリエンス、組織構造を扱います。エンドポイントの命名規約やページングの実装パターン、生成AI・MCPは扱っていません。

Amazonで見る楽天で見るYahoo!ショッピングで見る

※価格・在庫は変動します。最新の情報は各販売サイトでご確認ください。

4冊の使い分け#

役割と症状から選ぶための対応表です。刊行時期は、概念そのものより周辺技術の前提がどれくらいずれるかの目安です。

最初の1冊は2冊目か3冊目になるチームが多いはずです。1冊目は共通語がないときの底上げ、4冊目はサービスが複数あるときに効きます。

書籍だけでは埋まらない、エージェント固有の部分#

4冊のいずれも「エージェントに叩かせるAPIの本」ではありません。APIの側を整えたあとに残る次の3つは、自分たちで設計する部分です。

ツール定義の書き方は、API仕様書の流用では足りない#

OpenAPIの説明文をそのままツールのdescriptionにコピーしても、エージェントの選択精度は上がりません。Anthropicの公式ドキュメント「Define tools」は、ツール定義のベストプラクティスとして、非常に詳細な説明を書くこと(これがツール性能に最も影響する要素だとしています)、その説明にツールが何をするか、いつ使うべきか(そしていつ使うべきでないか)、各パラメータの意味と挙動への影響、ツールが返さない情報などの制限を含めること、各ツールの説明は最低でも3から4文を目安にすることを挙げています。さらに、関連する操作を少数のツールに集約すること、複数のサービスにまたがる場合はツール名に接頭辞を付けて名前空間を切ること、レスポンスはシグナルの高い情報だけを返す設計にすることも挙げられています。

同社のエンジニアリング記事「Writing effective tools for AI agents」も同じ方向です。ツールは多ければよいというものではないとし、list_contacts ではなく search_contacts を実装する、空き時間の検索と予約を1回で扱う schedule_event にする、といった統合の例を挙げています。レスポンスはページネーション、範囲選択、フィルタリング、切り詰めの組み合わせでサイズを制御することを勧め、エラーメッセージは不透明なエラーコードやスタックトレースではなく、具体的で実行可能な改善点を明確に伝えるべきだとしています。

ツール定義に関する上記の記述は、Anthropicの公式ドキュメント「Define tools」および同社のエンジニアリング記事「Writing effective tools for AI agents」(いずれもfrontmatterのsources)に記載されている内容の要約です。他社のモデルやフレームワークで同じ指針が最適である保証はありません。使用するモデルの提供元ドキュメントを別途確認してください。

注目したいのは、この指針の多くが3冊目の目次と重なることです。統合された粒度の高い操作は第7章の標準メソッドとカスタムメソッド、名前空間は第3章の名前付け、レスポンスの絞り込みは第21章と第22章の話です。ツール定義の良し悪しは、その下にあるAPIの良し悪しに引きずられます。だからAPI側を先に整えるほうが近道になります。

認可の主体をどこに置くかは、API設計の外側の判断#

エージェントがサービスアカウントで動く構成にすると、依頼者の権限を超えた操作ができてしまいます。かといって依頼者のトークンを引き回す構成にすると、トークンの寿命やスコープ、監査ログの記録単位を設計し直す必要が出ます。どちらを選ぶかは業務要件と統制方針の問題で、API設計書には書かれていません。

何を人間の承認に残すかは、可逆性で決める#

削除、送信、決済、外部への公開をエージェントに任せるかは、技術ではなく方針の問題です。3冊目の第25章「論理削除」と第27章「リクエストの検証」は方針を実装可能にする道具を与えますが、どこに線を引くかは決めてくれません。取り消せる操作は任せ、取り消せない操作は承認を挟む、という可逆性を軸にした整理が実務では扱いやすいはずです。

明日からできる最初の一歩#

本を読み終えてからAPIを直そうとすると、たいてい着手できません。いま繋ごうとしているAPIに、小さく順番に足していくほうが現実的です。

この順序は、4冊が扱う内容をエージェント導入の文脈に置き換えたものです。1は1冊目と3冊目、2は1冊目と2冊目、3は2冊目と3冊目、4はAnthropicのドキュメント、5は3冊目、6は2冊目と4冊目に対応します。逆に言えば、どの手順で手が止まったかで読むべき本が決まります。

よくある質問#

まとめ#

エージェントを社内システムに繋ぐ作業は、新しい技術の導入というより、これまでUIと人間の慣れが吸収していた曖昧さの精算です。命名が曖昧でも、エラーが200で返っても、再送で二重に処理されても、人間の担当者は気づいて回避してきました。エージェントは回避しません。書かれているとおりに、書かれていないことは推測して動きます。

今回紹介した4冊は守備範囲が違います。Webの語彙を揃える本、1本のAPIの設計判断を型にする本、操作の形をパターン集として持つ本、分散した先の現実と契約の進化を扱う本。いずれも生成AIの本ではありませんが、だからこそモデルが何世代変わっても使えます。まずは自分の状況に対応する1冊を選び、最初に繋ぐ数本のAPIを整えるところから始めてみてください。