【入門】APIとは何か？RESTの設計原則から学ぶWeb APIの基礎
本稿は、「API」および「REST API」という言葉を初めて学ぶ開発者を対象とする。Webサービスの連携に不可欠なこれらの技術について、その定義、設計思想、そして具体的な実装原則を体系的に解説することを目的とする。
1. API（Application Programming Interface）の定義
APIとは、ソフトウェアコンポーネント同士が互いに情報をやり取りするために使用されるインターフェースの仕様である。内部実装の詳細を隠蔽（カプセル化）し、外部に対して機能の呼び出し規約のみを公開することで、ソフトウェア間の連携を容易にする。
概念モデル：寿司屋における役割分担
この概念を、寿司屋の役割分担に置き換えてモデル化する。
- あなた（クライアント）: サービスを利用するアプリケーションやWebブラウザ。
- 寿司屋の大将（サーバー）: データや機能を提供する本体。
- 店員（API）: クライアントとサーバー間のリクエストとレスポンスを仲介するインターフェース。
あなたは、店員という決められた窓口（API）を介してのみ、大将（サーバー）のお寿司を食すことができる。
- リクエスト: あなたが店員に対し、「にぎり御膳をください」という仕様に沿った形式で要求を送信する。
- 処理: 店員はリクエストを解釈し、大将に伝達する。大将は要求された処理（寿司を握る）を実行する。
- レスポンス: 店員は処理結果（にぎり御膳）を、仕様に沿った形式であなたに返却する。
このように、API（店員）はシステム間の明確な境界線と、そこに置かれた標準的な対話手段であると言える。
2. REST APIのアーキテクチャスタイル
APIの設計思想にはいくつかの種類が存在するが、現在のWeb APIにおいて主流となっているのがREST (Representational State Transfer) と呼ばれるアーキテクチャスタイルである。
| 特徴 | SOAP API | REST API | GraphQL API |
|---|---|---|---|
| 設計思想 | 厳格なプロトコル | シンプルな設計原則の集合 | クライアント主導のデータ取得 |
| データ形式 | XML | JSON, XML, Textなど柔軟 | JSON |
| 通信プロトコル | HTTP, SMTPなど | 主にHTTP/HTTPS | 主にHTTP/HTTPS |
| 様式 | 銀行窓口（厳格な手続きと文書形式） | レストランのメニュー（定義された品目と注文方法） | オーダーメイド（要求仕様を詳細に記述） |
RESTは厳格なプロトコルではなく、スケーラブルなWebサービスを構築するための一連の「制約（原則）」である。この原則に従って設計されたAPIを「RESTful API」と呼ぶ。
RESTの主要な設計原則
RESTを構成する6つの主要な原則を解説する。
1. クライアント/サーバー分離
ユーザーインターフェース（UI）を持つクライアントと、データを管理するサーバーは、互いに独立したコンポーネントとして分離されるべきである、という原則。
- 寿司屋の例: 「客席」と「厨房」の役割が明確に分離されている状態。店員（API）が両者を仲介するため、厨房の改修（サーバーの更新）が客席の利用方法（クライアントのUI）に直接影響を与えることはない。
2. ステートレス（Stateless）
サーバーは、クライアントの状態（セッション情報など）を一切保持してはならない、という原則。各リクエストは、それ自体で処理に必要なすべての情報を含んでいなければならない。
- 寿司屋の例: 店員は客の過去の注文履歴を記憶しない。注文は常に「どの客が何を求めているか」という完全な情報を含んでいなければならない。「いつもの」という注文は受け付けられない。これにより、どの店員が対応しても同じ結果が保証され、店の規模拡大（サーバーのスケールアウト）が容易になる。
3. 統一インターフェース（Uniform Interface）
リソースへのアクセス方法が、コンポーネント間で統一されているべきである、というRESTにおける最も重要な原則。
- 寿司屋の例: 全ての席に「カウンター3番」のような一意の識別子(URI)が割り当てられ、注文伝票には「食事」「飲物」といった形式（メディアタイプ)が明記される。これにより、誰が扱っても誤解なくやり取りが可能になる。
4. 階層化システム（Layered System）
クライアントは、通信相手のサーバーが最終的なエンドポイントであるか、あるいは中継サーバーであるかを意識する必要はない、という原則。
- 寿司屋の例: 客は特定の店員に注文するが、その注文が厨房内で他の補助担当者を経由していたとしても、客はその内部構造を知る必要はない。
5. キャッシュ可能性（Cacheability）
レスポンスには、それがキャッシュ可能か否かの情報が含まれているべきである、という原則。
- 寿司屋の例: 卓上の醤油は、客が自由に利用できるキャッシュされたリソースである。毎回店員を呼んで醤油を要求する必要はなく、これによりシステム全体のパフォーマンスが向上する。
6. コードオンデマンド（Code on Demand）
サーバーがクライアントに対して実行可能なコードを送信し、クライアントの機能を一時的に拡張できる、という唯一の任意の原則。
- 寿司屋の例: 特定の料理と共に「この塩を振ってお召し上がりください」という指示書（プログラム)が提供され、客はそれに従って新しい食べ方を実行できる。
3. RESTful APIの実装パターン
RESTの原則、特に「統一インターフェース」は、具体的な実装において以下のパターンを生み出す。
リソースの表現：URL（URI）
URLは、操作対象となる「リソース（資源）」を名詞で表現する。
- 非推奨な例: /getAllUsers, /createNewUser (URLに動詞が含まれている)
- 推奨される例: /users (ユーザーというリソースの集合体を示す)
リソースへの操作：HTTPメソッド
リソースに対して実行したい操作は、動詞としてHTTPメソッドで表現する。
- GET /users: ユーザーのリストを取得する。
- POST /users: 新しいユーザーを作成する。
- PUT /users/123: IDが123のユーザー情報を更新する。
- DELETE /users/123: IDが123のユーザーを削除する。
この「URLは名詞、HTTPメソッドは動詞」という役割分担が、直感的で予測可能なAPI設計の基本である。
結論
- APIは、システム間の機能を標準化された方法で利用するためのインターフェースである。
- RESTは、Webの原則（HTTPなど）を活かしてスケーラブルなシステムを構築するためのアーキテクチャ原則である。
- 優れたRESTful APIは、「リソース（名詞）」と「操作（動詞）」を明確に分離して設計される。
本稿で解説した基本原則を理解することは、現代的なWebサービス開発における第一歩となる。