APIとは
API（Application Programming Interface／アプリケーション・プログラミング・インターフェース／エーピーアイ）は、ソフトウェア同士が機能やデータをやり取りするための規則や接点です。呼び出せる操作、渡す値、戻る値、失敗の表し方を契約として公開します。
APIはWebだけの言葉ではありません。programmingライブラリーの機能、OSのシステム呼び出し、機器ドライバーのインターフェース、データベースクライアント、HTTPで呼ぶWeb APIなどを含む広い概念です。
利用者が内部実装を直接操作するのではなく、公開されたインターフェースへ決められた形で要求します。実装を取り替えても契約を保てば、呼び出し側への影響を抑えられます。
API契約に含まれるもの
機能名、オブジェクト方式、ソケット、URLエンドポイントなどで入口を識別します。
取得、作成、更新、削除、検索、計算などの操作と副作用を定義します。
必須・任意、型、形式、範囲、既定値、検証規則を決めます。
API鍵、トークン、証明書等で認証し、漏えい時の失効方法も設計します。
戻り値、HTTP状態、ヘッダー、本文、pagination等を安定したスキーマで返します。
入力誤り、認証、権限、競合、レート制限、一時障害を区別します。
三つの代表的なAPI
ライブラリーAPIは同じ処理内で機能やクラスを呼びます。OS APIはファイル、処理、ネットワーク等をシステム呼び出し経由で利用します。Web APIはネットワーク越しにHTTP等を使って呼びます。
Web APIでも、REST、RPC、GraphQL、イベントストリームなど設計スタイルは複数あります。「API」と「REST API」を同義にしません。
HTTP APIの一回の呼び出し
- エンドポイントを選ぶ基礎URL、パス、バージョン、問い合わせ条件を組み立てます。
- 要求を作る方式、ヘッダー、認証情報、コンテンツタイプ、本文を契約に合わせます。
- 境界で検証するTLS、認証、認可、レート制限、スキーマ、大きさを確認します。
- サービスが処理する業務規則とデータベーストランザクションを実行します。
- 応答を読む状態、ヘッダー、本文を読み、成功・修正・再試行を判断します。
認証と認可
認証は呼び出し主体を確かめ、認可はその主体が対象リソースへ操作できるかを判断します。有効なトークンを持っていても、別利用者のデータを読めるとは限りません。
認証情報をURL問い合わせやソースコードへ固定すると、ログ・履歴・リポジトリへ漏れる危険があります。短い権限、期限、回転、秘密情報管理者、監査ログを使います。
スキーマとdocumentation
人向けの説明には目的、前提、例、エラー、レート制限、変更履歴を含めます。machine-readableなスキーマがあれば、クライアント生成、検証、mock、試験、documentation作成を補助できます。
OpenAPIはHTTP APIのインターフェースを記述する仕様の一つです。OpenAPI文書があること自体は、そのAPIがRESTの全制約を満たすことや、実装が文書通りであることを保証しません。
バージョンと互換性
フィールド追加、必須化、型変更、意味変更、削除はクライアントを壊す可能性があります。事業者はdeprecation期間と移行方法を示し、利用側は未知フィールドを安全に無視できる設計を選びます。
URL、ヘッダー、メディアタイプ等でバージョンを分ける方法があります。数字を変える前に、何がbreaking変更かを契約試験で確かめます。
タイムアウト・再試行・冪等性
タイムアウトは「サーバーが処理しなかった」とは限りません。処理済みなのに応答だけ届かなかった可能性があります。作成・課金等を無条件に再送すると二重実行になります。
安全に再試行できる操作、冪等性鍵、条件付き更新、要求IDを設計します。再試行は一時障害だけに、上限・待ち時間を増やす再試行・ジッターを付けます。
paginationとレート制限
大量一覧はページやcursorへ分けます。取得途中でデータが増減する場合の順序と重複・欠落を仕様で決めます。全件を一度に返す設計はメモリーと応答時刻を悪化させます。
レート制限は一定期間の回数、同時実行数、計算量等を制限します。残量や再試行時刻が返る場合はそれに従い、複数クライアントが同時に再試行する集中を避けます。
APIとWebhook
通常のAPI呼び出しは利用側が必要な時に事業者へ要求します。Webhookはイベント発生時に事業者側から登録URLへHTTP要求を送ります。どちらも認証、スキーマ、バージョン、再試行、重複への対応が必要です。
APIは、内部実装を隠したままソフトウェア機能を利用する契約です。入口だけでなく、入力、権限、成功、失敗、互換性、再試行まで揃って初めて安全に連携できます。
HTTP APIをmachine-readableなcontractとして記述する標準例：OpenAPI Specification