API

🐾 猫で例えると？

ダンボールハウスの玄関を、決められた方法でやり取りする窓口に見立てます。相手の内部を直接触らず、窓口の約束に従って依頼する点が対応します。ただし窓口があるだけで安全になるわけではなく、認証や入力検証は別に設計します。

💻 IT現場における「API」とは？

現代のシステム開発において、APIは「車輪の再発明」を防ぐための最重要ピースです。例えば、自社アプリの中に地図を表示したいとき、わざわざ地球の測量から始めるエンジニアはいません。Googleが公開している地図のAPIを呼び出すことで、自社アプリ内に一瞬で高度な地図機能を組み込むことができます。

実務では、Webブラウザとサーバー間、あるいはサーバー同士がHTTP/HTTPS通信を通じてデータをやり取りする「Web API」が主流です。認証、決済、天気データの取得、SNS連携など、あらゆる機能がAPIという窓口を通じてカプセル化され、流通しています。開発者は内部の複雑なコードを知らなくても、定められた仕様に沿って要求（リクエスト）を送り、応答（レスポンス）を受け取ります。

⚠️ APIの仕組みと注意点

APIを利用・構築する際には、通信の規律である「プロトコル」や、やり取りするデータの「フォーマット」を統一する必要があります。現在のWeb開発では、ステートレスな通信を行うRESTの原則に則った「REST API」が広く普及しており、データ形式には軽量なJSONが採用されることが一般的です。

JSONを用いたAPIリクエストとレスポンスの例

次はGET /api/v1/users/8への、説明用のJSON応答です。URLや項目名はこの例の契約であり、すべてのAPIに共通の形式ではありません。

{
  "userId": 8,
  "name": "Amesho",
  "role": "viewer",
  "isFriendly": true
}

実際に連携するには、項目の型、必須かどうか、値なしの表現、HTTPステータス、失敗時の形式も確認します。JSONという形式が一致するだけでは、意味まで自動的に一致するわけではありません。

🛠️ APIを賢く使うためのポイント

外部のAPIは非常に便利ですが、他社のリソースに依存することになるため、設計や利用時にはいくつかの重要な罠に気をつける必要があります。

• レートリミット（回数制限）の把握： 短時間に大量のリクエストを送信するとエラーになるため、負荷を考慮した設計が必要です。
• 認証とセキュリティの徹底： APIキーやアクセストークン（OAuthなど）が外部に漏洩すると、不正アクセスの原因になります。
• 互換性と変更のルール： URLに/v1を付けるのは一つの方法です。項目を削除する、型を変えるといった変更の影響を把握し、更新方法や旧版の扱いを利用側へ伝えます。

箱の入口から顔を出すアメショのように、APIは相手とやり取りする窓口です。利用するときは、渡す項目、返ってくる形式、認証、エラー時の扱いを確認しましょう。窓口の約束を先に読むと、連携時の食い違いを減らせます。