API（アプリケーション・プログラミング・インターフェース）

この用語の意味

API（Application Programming Interface）は、プログラムから利用できる操作、入力、出力、失敗時の振る舞いを契約として公開する仕組みである。利用側は内部実装を知らなくても、定められた呼び出し方で機能を使える。

計算の考え方

APIは接点を表す概念なので、共通の計算式はない。個別APIは、目的に応じて複数の運用指標で評価する。 成功率 | 対象となる要求のうち正常に完了した割合 | 分母に含めるエラーを先に決める 応答時間 | p50・p95・p99などの分布 | 操作やデータ量ごとに分ける 利用開始 | 初回成功呼び出し数や価値到達時間 | 使える状態までの摩擦を見る

含めるもの / 含めないもの

判断の境界は公開された契約である。画面や内部DB、非公開の補助関数は、明示されない限りAPIの一部ではない。 含める | 操作、引数、データ形式、認証・認可、応答、エラー、制限、互換性の約束 含めない | UI画面、内部テーブル、非公開コード、配置構成などの実装詳細 明示する | 通信方式、版管理、レート制限、冪等性、ページング、廃止予告、問い合わせ先

何が数字を動かすか

APIの実用性は、契約の明瞭さ、意味の一貫性、安全性、互換性、可観測性、開発者体験で決まる。 契約設計 | 名称、スキーマ、エラーを予測可能にする 変更管理 | バージョン、廃止予告、移行手順をそろえる 運用品質 | 認可、制限、再試行、冪等性、追跡情報を設計する 利用者の声 | 初回失敗や問い合わせから仕様の穴を見つける

こんな場面で役立つ

他チームや顧客が依存してよい機能の範囲を決める。 互換性と廃止を、実装都合ではなく提供上の約束として扱える。 セキュリティ、信頼性、サポートの担当者が同じ契約をレビューできる。

• 他チームや顧客が依存してよい機能の範囲を決める。
• 互換性と廃止を、実装都合ではなく提供上の約束として扱える。
• セキュリティ、信頼性、サポートの担当者が同じ契約をレビューできる。

実務での使い方

• APIはApplication Programming Interfaceの略であり、単なるWebサイトやバックエンドの別名ではない。
• HTTPやRESTは実装上の選択肢で、API全体の定義ではない。
• 正常系だけでなく、エラーと変更方法まで契約に含める。
• 利用者の成果とシステムの稼働状態を分けて測る。

判断するときの注意点

公開前に、互換性と障害対応の責任者を決める。 認可の境界が誤っていれば、仕様書が整っていても安全ではない。 非冪等な操作を自動再試行すると、処理が重複することがある。 提供側が正常でも、破壊的なスキーマ変更は利用側を停止させる。

• 認可の境界が誤っていれば、仕様書が整っていても安全ではない。
• 非冪等な操作を自動再試行すると、処理が重複することがある。
• 提供側が正常でも、破壊的なスキーマ変更は利用側を停止させる。

一緒に見る指標

技術的な健全性に加え、利用者が接続し障害から復旧できるかを測る。 可用性・遅延 | サービス目標に対する実運用の状態 エラー内訳 | 入力不備、認可失敗、流量制限、提供側障害を分離 初回成功までの時間 | 文書、認証情報、サンプル、導入手順をまとめて評価 旧版トラフィック | 廃止前の移行リスクを把握

具体例

小売企業が配送会社向けに注文状況APIを提供する。注文IDを受け取り、定義済みの状態を返し、配送会社ごとの権限を確認する。レート制限と90日前の廃止予告を定め、初回成功、p95遅延、認可失敗、旧版利用を監視する。新しい配送項目は任意項目として追加し、既存利用者を壊さない。

似ている言葉との違い

API | ソフトウェア向けの機能・データ利用契約 | ローカルでも遠隔でもよい UI | 人が操作する画面 | プログラム呼び出しとは利用者が違う プロトコル | HTTPなど通信の規則 | APIが利用する手段の一つ SDK | 特定言語からAPIを呼びやすくするコード | 契約そのものではない API文書 | 呼出し、入力、応答、エラー、変更を人と機械が読める形で説明する情報 | APIの利用方法を示すが、稼働中の実装そのものではない

よくある勘違い

• すべてのAPIがREST APIとは限らない。ライブラリ、OS、機器、RPCにもAPIがある。
• APIはURL一本ではない。操作、データ形式、権限、エラー、変更方針まで含む。
• 仕様書を自動生成すれば良い統合になるわけではない。意味、例、支援、安定運用が必要である。

よくある質問

参考・出典