Tsuzura

APIとは？システム同士の頼み方と返し方

AIへサービス作成を頼む前に、画面やバックエンドとAPIを混同せず、一つの依頼と返答を確認票へまとめる方法を説明します。

公開日
更新日

APIは、あるソフトウェアが別のソフトウェアの機能やデータを、決められた方法で利用するための接点です。NISTの用語集も、決められた書き方でシステムへ接続する接点と、プログラムから機能を使うライブラリ関数の両方をAPIの定義に含めています。

ここでいうソフトウェアは、コンピュータやスマートフォンで動くプログラムの総称です。ブラウザは画面を表示して操作を受け取るプログラム、サーバーはネットワークの向こうで依頼を受けるコンピュータやプログラムです。ネットワークはデータを運ぶ通信の経路、HTTPはその経路で依頼と返答をやり取りするための規則です。

この記事では、ネットワーク越しに利用するAPIをWeb APIと呼び、そのうちHTTPを使うものを扱います。こうしたAPIでは、その接点に加えて「誰が、どこへ、何を頼み、何を送り、成功時と失敗時に何が返るか」を約束として確認します。AIへサービス作成を頼む前に、この一往復を自然文で説明し、空欄の「APIやり取り確認票」へ移せれば完了です。実装や公開は扱いません。

APIはHTTPだけではない

APIは、すべてがHTTPで動くわけではありません。OpenAPI Specification 3.2.0は、HTTP APIの機能を人とコンピュータが理解できる形で記述する仕様です。

同じプログラムの中からライブラリの関数を呼ぶ接点も、ライブラリAPIと呼ばれます。そこではHTTPの依頼方法や結果コードを使うとは限りません。Web APIの言葉を、API全般の必須条件にはしません。

APIと似ているものを呼び分ける

混同を避けるため、この記事では役割を次のように呼び分けます。

言葉 この記事で指すもの APIとの関係
画面・UI 人が見て操作する入口 裏でAPIを呼ぶことはあるが、画面そのものはAPIではない
データベース・DB データを保存し、取り出す場所 APIが利用することはあるが、保存場所そのものはAPIではない
通信回線・ネットワーク データを運ぶ経路 何を頼めるかという約束は決めない
バックエンド サーバー側で動く処理や部品のまとまり APIを提供することはあるが、全体がAPIとは限らない
API key 呼ぶ側の識別や利用量管理などに使う資格情報 接点や約束そのものではない

API keyだけで重要なデータや操作を守れるとは限りません。OWASP REST Security Cheat Sheetも、重要なデータや操作をAPI keyだけで保護しないよう示しています。確認票には実際の値を書かず、承認済みの保管場所と管理責任者への参照だけを残します。

Web APIの一往復を言葉にする

まず三つの役割を決めます。

  • 機能やデータを使いたいソフトウェアが、呼ぶ側です。
  • 機能やデータを提供するソフトウェアが、提供側です。
  • 呼ぶ側が頼む一件の仕事が、操作です。

呼ぶ側から提供側へ送る依頼をリクエスト（request）、提供側から返す返答をレスポンス（response）と呼びます。RFC 9110が定めるHTTPでは、クライアントがサーバーへリクエストを送り、サーバーがレスポンスを返します。この記事ではクライアントを呼ぶ側、サーバーを提供側として読み替えます。

次に、一往復を記録する言葉を日常語から対応させます。

  1. 依頼を送る宛先が、エンドポイント（endpoint）です。HTTP APIではURLやその一部で表します。
  2. 宛先で何を頼むかを表す依頼の種類が、HTTPメソッド（HTTP method）です。HTTP上の意味を確認して選びます。
  3. 依頼や返答に添える補助情報が、ヘッダー（header）です。データの種類などを運びます。
  4. ヘッダーとは別に送る主なデータが、ボディ（body）です。操作によっては送りません。
  5. 返答の結果を示す結果コードが、ステータス（status）です。HTTPでは個々のステータスコードに意味があります。
  6. 処理できなかった理由と次の行動を伝える失敗情報が、エラー（error）です。
  7. データの並べ方を表す形式が、フォーマット（format）です。JSONなどが候補になります。
  8. その形式の中で、項目名、型、必須かどうか、許す値を表すデータの形が、スキーマ（schema）です。

HTTP APIの一つの操作は、宛先とHTTPメソッドの組み合わせで記述できます。OpenAPI SpecificationのPaths Objectにも、この関係が定義されています。リクエストの意味はメソッドが主に示し、レスポンスの内容の意味はメソッド、ステータス、レスポンスの項目などとの組み合わせで決まります。RFC 9110のHTTP Semanticsを、個別APIの業務上の意味と分けて確認します。

スキーマは入力と出力の形をそろえる助けになります。OpenAPI SpecificationのMedia Type Objectでは、リクエストやレスポンスなどの内容をスキーマで表せます。ただし、形が正しくても、呼んだ人やソフトウェアにその操作を許してよいとは限りません。OWASP Authorization Cheat Sheetが示すように、操作の許可はリクエストごとに確認します。

失敗時は、ステータス、外へ出す理由、呼ぶ側の次の行動を対応させます。RFC 9457のProblem Detailsは、HTTP APIのエラーを機械が読める形で表す選択肢です。必須形式ではありません。内部の処理記録、構成、秘密、他人のデータはエラーへ含めません。

一つのやり取りを決める

確認する項目は、確認済みの既存事実、新規設計案、未確認の事実の三つに分けます。既存APIのエンドポイント、項目、エラーは、コード、承認済み文書、提供側の公式資料で確認できたものだけを既存事実にします。新しく設計する内容は案と明記し、人が承認した時点で契約にします。未確認の事実をもっともらしく補いません。

一往復は、次の順で一文にできます。

［呼ぶ側］が［提供側］の［エンドポイント］へ［HTTPメソッド］で［操作］を頼み、［ヘッダーとボディ］を送り、成功時は［ステータスと返るデータ］、失敗時は［条件、ステータス、エラー、次の行動］を受け取る。

この文を作るときは、一つの操作だけを選びます。画面、DB、バックエンド内部の処理順まで同時に決めません。結果を変える未確認事項、権限、秘密や個人データの扱いが残るなら、担当者を決めてHOLDにします。HOLDは、確認が終わるまで後続の設計や実装へ渡さないという、この記事で使う状態です。

安全に利用する境界を分ける

APIの形が決まっても、安全に利用できるとは限りません。確認票では次を分けます。

  • 通信を暗号化するHTTPSを使い、パスワード、トークン、API keyなどの資格情報を、URL本体やURLの「?」以降に付けるクエリ文字列へ入れません。OWASP REST Security Cheat SheetのHTTPSとSensitive Information in HTTP Requestsを確認します。
  • 本記事の安全上のルールとして、ブラウザへ配るコードに秘密情報を埋めません。別のサービスに限られた操作を許すための枠組みであるOAuth 2.0を、ブラウザアプリで使う場合、コードへ静的に含めた共有のクライアントシークレット（クライアント用の秘密情報）は、秘密の証明として扱えません。IETF Internet-Draft第27版がこの境界を説明しています。この文書は2026年8月20日時点で策定中（work in progress）であり、OAuth 2.0の範囲に限った根拠です。
  • 認証（authentication）は、人やソフトウェアが誰であるかを確かめる手続きです。認可（authorization）は、認証で確かめた人やソフトウェアに、対象のデータや操作を許してよいか判断する手続きです。NIST SP 800-63-4のAuthentication ProcessとOWASP Authorization Cheat Sheetを別の判断として参照します。
  • 提供側は、届いたデータの型、長さ、値、意味を検証し、呼んだ人やソフトウェアが対象を操作できるかも、リクエストごとに確認します。OWASP Input Validation Cheat SheetとAuthorization Cheat Sheetが根拠です。
  • リクエストには機能に必要なデータだけを含めます。RFC 9205のPrivacy Considerationsは、必要な情報だけを含めるよう仕様化することを勧めています。
  • ログにはパスワード、アクセストークン、キーなどの秘密を直接残しません。個人データも原則として残さず、必要な場合は目的、対象項目、マスク、閲覧権限、保持期間、責任者を確認します。OWASP Logging Cheat Sheetが、除外または保護する情報を挙げています。

具体的な認証方式、認可ルール、秘密情報の管理、ログイン状態の管理、テストは認証と認可の判断表へ渡します。この記事や確認票には、実際に使用中の資格情報や実際の個人データを書きません。

HTTP APIの運用条件を残す

ネットワーク越しのHTTP APIでは、待ち時間、再送、重複、利用量、データ量、変更への対応も必要です。具体値や実装方法は、要件と検証結果に合わせて後続で決めます。

条件 自然文で決める問い
タイムアウト（timeout） 何を何秒待って打ち切るか。打ち切り後の結果をどう確認するか
再試行（retry） どの失敗なら、誰が、いつ、何回まで再送してよいか
重複実行 同じ依頼が複数回来たとき、どんな影響が出るか
呼び出し回数（rate） 誰について、どの時間幅で、何回までとするか。超過時に何を返すか
データ量（size） 一回のリクエスト、ファイル、レスポンス、件数をどこまで許すか
版と変更互換性 変更後も既存の呼ぶ側が動くか。通知、移行、終了を誰が決めるか

HTTPの冪等なメソッドとは、同じリクエストを複数回送っても、サーバー上の意図した効果が一回と同じになるものです。RFC 9110のIdempotent Methodsは、非冪等なリクエストを、再送してよいと分かる場合などを除いて自動再試行しないよう示しています。タイムアウトと再試行を決めるときは、重複実行を同じ項目で確認します。

提供側はRetry-Afterで待ってほしい時間を示せますが、すべての失敗に共通する万能値ではありません。RFC 6585の429もリクエストが多すぎたことは示しますが、利用者の数え方や上限値までは決めません。

OWASP API4:2023は、タイムアウト、メモリ、アップロード容量、返す件数、同時操作、外部サービスの費用などを制限候補に挙げています。値は業務要件とリスクに合わせ、提供側で強制します。

HTTP APIは将来変更される可能性があります。RFC 9205のVersioning and Evolutionは、HTTPを使うアプリケーションが機能追加や互換性のない変更へ備える必要を示しています。版をURLへ入れるかなどの詳細には踏み込まず、既存の呼ぶ側への影響と移行責任者を残します。

AIは確認候補の整理まで

利用するAIコーディングツールを読み取り専用に設定できる場合に限り、既存コードと承認済み文書から次の候補を整理させます。

  • 呼ぶ側、提供側、既存のエンドポイントとHTTPメソッド
  • リクエストとレスポンスの項目、形式、スキーマ
  • 既に処理しているステータスとエラー
  • 矛盾、未確認、参照元が分からない項目

各候補には確認先を付けます。確認先は、ファイル、関数、仕様の版、公式文書のURLなどです。AIが自然に見えるエンドポイント、項目、エラーを出しても、実在を確認できなければ既存事実にしません。GitHubのAI生成コードのレビュー手引きも、存在しないAPIや無視された制約を確認候補に挙げています。

読み取り専用は、AI提供者へ情報が送られないという意味ではありません。OWASP Secure Coding with AI Cheat Sheetが示すように、送られる文脈を確認し、秘密を含むファイルを対象から外します。実際に使用中の資格情報や、顧客・利用者・従業員などの個人データは渡しません。機密のコードや文書も同様です。利用規約、保持、学習利用、処理地域、組織の承認が確認できない場合も送信せずHOLDにします。

新しい設計案は案、分からないことは未確認として残します。最終的な契約、権限、採否は人が元資料と差分を確認して決めます。AIは自分の候補を承認できません。

APIやり取り確認票

最初の一巡では、表の①から⑧を順に埋めます。

  1. 目的と対象版
  2. 呼ぶ側、提供側、一つの操作
  3. 送る情報
  4. 成功時の返答
  5. 分かっている失敗
  6. 未確認の項目
  7. 確認する担当者と期限
  8. 次に渡す設計

その後、残りの行を詳しく確認します。各行の状態には「確認済みの既存事実」「新規設計案」「未確認」のいずれかを書きます。「該当なし」と「未確認」を分け、秘密値や実際の個人データは記入しません。操作の許可、秘密、個人データ、責任者が未確認ならHOLDです。

項目 状態 記入欄
① この一往復の目的・対象版
② 呼ぶ側／提供側／一つの操作
契約の責任者・承認者
根拠にしたコード・文書・版
APIの種類：Web API／ライブラリAPI／その他
エンドポイント／HTTPメソッドと選定根拠
③ リクエストのヘッダー／ボディ／形式／スキーマ
④ 成功レスポンス：ステータス／ヘッダー／ボディ／スキーマ
⑤ 既知の失敗：条件／ステータス／エラー形式／次の行動
HTTPS／資格情報の送信場所／ブラウザへ配らない秘密
認証の確認先／操作を許可する人やソフトウェア・対象・操作
提供側で検証する型・長さ・値・意味・権限
必要最小限にするデータ／送らない個人データ
エラーとログへ出さない情報／必要なログの保護・保持
タイムアウト／再試行／重複実行
呼び出し回数／データ量／超過時のレスポンス
版／変更互換性／通知・移行・終了の責任者
AIへ渡さない情報／利用条件と組織承認
⑥ 未確認のエンドポイント・項目・エラー・条件
⑦ 未確認を確かめる人・根拠・期限
⑧ 次に渡す設計記事・担当者
人による最終判断：採用／棄却／HOLD

完了チェックリスト

  • APIを画面、DB、通信回線、バックエンド、API keyと区別して説明できる。
  • 呼ぶ側、提供側、一つの操作と、一往復の依頼・返答を特定した。
  • 宛先、依頼の種類、ヘッダー、ボディ、結果、エラー、形式、スキーマを確認先へ結び付けた。
  • 既存事実、新規設計案、未確認を分け、未確認のエンドポイント、項目、エラーを創作していない。
  • HTTPS、秘密の置き場所、認証、認可、提供側の検証、必要最小データ、ログを確認した。
  • タイムアウト、再試行、重複実行、呼び出し回数、データ量、版と変更互換性を確認した。
  • AIへ実際に使用中の資格情報、個人データ、機密情報を渡さず、候補を人が確認した。
  • 未決事項をHOLDにし、同じ確認票を責任者と次の設計へ渡せる。

次の設計へ渡す

確認票の一往復を人が承認したら、必要な後続だけを選びます。

この記事はAPIの概念と、自然文で表した一往復までです。後続記事の成果物をここで作り直さず、APIやり取り確認票を入力として渡します。

出典