REST API（Representational State Transfer）とは

REST（Representational State Transfer）は、分散ハイパーメディアシステム向けのアーキテクチャ設計原理です。HTTPプロトコルを活用して、シンプルで拡張性の高いWebサービスを構築するための標準的な設計指針として広く採用されています。RESTful APIは、URLリソースとHTTPメソッドを組み合わせることで、直感的で保守性の高いAPI設計を実現します。

REST APIの読み方

日本語読み：レスト（primary）、アールイーエスティー（common）
英語読み：rest（/rɛst/）

REST APIの仕組み

定義と基本概念

RESTはRoy Fieldingが2000年にカリフォルニア大学アーバイン校での博士号取得論文において提唱したアーキテクチャ設計原理です。Fieldingは、Webの成功を分析し、その設計原理を体系化することで、スケーラビリティと単純性の両立を実現するRESTの概念を生み出しました。

REST APIは単なるテクニックではなく、設計思想であり、以下の6つの制約原則から構成されています：

• クライアント-サーバー（Client-Server）：クライアントとサーバーが独立して進化できるよう、関心を分離します。
• ステートレス（Stateless）：各リクエストは完全独立し、サーバー側でセッション状態を保持しません。これにより、スケーラビリティが向上します。
• キャッシュ可能（Cacheable）：レスポンスはキャッシュ可能であると明示できます。ネットワークトラフィックとレスポンス時間を削減します。
• 統一インターフェース（Uniform Interface）：クライアントとサーバー間の通信インターフェースが統一されています。
• レイヤー化システム（Layered System）：クライアントは直接サーバーに接続しているかどうかを知ることができません。中間層（プロキシ、ロードバランサーなど）を配置可能です。
• オンデマンドコード（Code on Demand）：オプション的な制約で、サーバーからコード（JavaScript等）をダウンロードして実行することができます。

RESTfulという用語は、これらのREST制約を遵守するアーキテクチャやAPIを指します。

HTTPメソッドとRESTful操作

REST APIはHTTPメソッドを活用して、以下のような基本的なCRUD（作成・読取・更新・削除）操作を実現します：

• GET：リソースの取得（読み取り）。サーバー上のデータを変更しないセーフなメソッドです。
• POST：新しいリソースの作成。リクエストボディにデータを含めます。
• PUT：既存リソースの完全な置き換え。リソース全体を指定する必要があります。
• PATCH：既存リソースの部分的な更新。特定のフィールドのみを変更します。
• DELETE：リソースの削除。

コード例

JavaScript（fetch API）でのGET実装例：

// ユーザー情報を取得
fetch('https://api.example.com/users/123')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

JavaScriptでのPOST実装例：

// 新しいユーザーを作成
const newUser = {
  name: 'John Doe',
  email: 'john@example.com'
};

fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(newUser)
})
  .then(response => response.json())
  .then(data => console.log('Created user:', data))
  .catch(error => console.error('Error:', error));

cURL でのリクエスト例：

# GET リクエスト
curl https://api.example.com/users/123

# POST リクエスト
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

# PUT リクエスト
curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com"}'

# DELETE リクエスト
curl -X DELETE https://api.example.com/users/123

HATEOAS（Hypermedia）

REST制約の一部である「統一インターフェース」には、HATEOAS（Hypermedia As The Engine Of Application State）が含まれます。これはレスポンスにハイパーリンクを含め、クライアントが次に何ができるかを発見的に知ることができる設計です。

HATEOAS の例：

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": {
      "href": "https://api.example.com/users/123"
    },
    "all_users": {
      "href": "https://api.example.com/users"
    },
    "delete": {
      "href": "https://api.example.com/users/123",
      "method": "DELETE"
    }
  }
}

コンテンツネゴシエーション

RESTful APIは、クライアントが希望するデータ形式（JSON、XML、YAML等）をリクエストで指定することができます。サーバーはAcceptヘッダに基づいて、適切な形式でレスポンスを返します。

// JSONを要求する例
fetch('https://api.example.com/users/123', {
  headers: {
    'Accept': 'application/json'
  }
});

バージョニング戦略

API が進化する際、クライアントとの互換性を保つため、複数のバージョンをサポートする必要があります。一般的なバージョニング戦略：

• URLパス型：/api/v1/users、/api/v2/users など、URLに明示的にバージョンを含める。
• クエリパラメータ型：/api/users?version=1 など、クエリパラメータでバージョンを指定。
• ヘッダ型：Accept: application/vnd.company.v1+json など、Acceptヘッダでバージョンを指定。

REST vs SOAP vs GraphQL：比較

Webサービスの設計パラダイムは複数存在します。REST、SOAP、GraphQLの主な違いは以下の通りです：

よくある誤解

誤解1：「REST = JSON」

REST のアーキテクチャ制約には、特定のデータ形式は規定されていません。JSON が広く採用されているのは利便性の高さからであり、XML、YAML、Protocol Buffers なども使用できます。

誤解2：「すべての HTTP API が REST」

REST の 6 つの制約を満たさない API は、単に HTTP API であり、RESTful API ではありません。例えば、RPC スタイルの設計（`/api/getUserById` など）は REST ではなく、HTTP ベースの RPC です。

誤解3：「REST は古い」

REST は設計原理であり、パラダイムシフトの対象ではありません。GraphQL や gRPC は特定のユースケースに最適化されていますが、REST は今なお Web API の標準設計手法として広く採用されています。

誤解4：「REST は常に最良の選択」

API 設計には、要件に応じた複数の選択肢があります。リアルタイム通信や複雑なクエリが必要な場合は、WebSocket、GraphQL、gRPC などの選択肢も検討する必要があります。

REST API 設計のベストプラクティス

• リソース指向設計：名詞を基本としたエンドポイント設計（例：`/users`、`/posts`）。
• 適切な HTTP ステータスコード：200（成功）、201（作成）、400（不正な要求）、404（見つからない）、500（サーバーエラー）など、セマンティックに正しいコードを使用。
• ステートレス設計：各リクエストが完全独立するよう設計。
• API ドキュメント：OpenAPI（Swagger）などを使用して詳細なドキュメントを提供。
• セキュリティ：認証（API キー、OAuth）、HTTPS、レート制限などを実装。
• バージョニング：互換性を保ちながら API を進化させるための戦略。
• エラーハンドリング：詳細なエラーメッセージと適切なステータスコードを返す。

FAQ（よくある質問）

Q1：REST API の認証方法は？
A：API キー、OAuth 2.0、JWT（JSON Web Token）など、複数の方法があります。OAuth 2.0 はサードパーティアプリの認可に適し、API キーはシンプルな実装が必要な場合に使用されます。

Q2：REST API のレート制限とは何か？
A：特定時間内のリクエスト数を制限する仕組みです。API の過負荷防止やセキュリティ対策に使用されます。

Q3：REST API のキャッシング戦略は？
A：Cache-Control、ETag、Last-Modified ヘッダを活用して、HTTP キャッシュを活用します。ブラウザやプロキシによるキャッシング効率が高まります。

Q4：CORS（Cross-Origin Resource Sharing）とは？
A：異なるオリジン（ドメイン）からのリクエストを許可するメカニズムです。クライアント側からの CORS リクエストに応答するため、サーバーは適切なヘッダを返す必要があります。

Q5：REST API は JSON で応答する必要があるか？
A：いいえ、REST はデータ形式を規定していません。クライアントが Accept ヘッダで希望する形式に応じて、JSON、XML、その他の形式で応答できます。

参考資料・関連キーワード

• Roy Fielding（2000年）『 Architectural Styles and the Design of Network-based Software Architectures』博士号取得論文
• HTTP/1.1 仕様（RFC 7231）
• OAuth 2.0（RFC 6749）
• OpenAPI Specification（旧 Swagger）
• RESTful Web Services：Leonard Richardson, Sam Ruby 著
• 関連技術：HTTP、API、JSON、XML、HATEOAS、マイクロサービス、gRPC、GraphQL、Web サービス

まとめ

REST（Representational State Transfer）は、Roy Fielding によって 2000 年に提唱された、分散ハイパーメディアシステム向けのアーキテクチャ設計原理です。クライアント-サーバー、ステートレス、キャッシュ可能性、統一インターフェース、レイヤー化システムの 5 つの必須制約とオプションのコードオンデマンド制約から構成されています。

REST API は HTTP メソッド（GET、POST、PUT、PATCH、DELETE）とURLリソースを組み合わせることで、シンプルで拡張性の高い Web サービスを実現します。JSON がデータ形式として広く採用されていますが、REST 仕様では特定の形式を強制していません。

REST の主な利点は、シンプルさ、HTTP キャッシングの活用、ステートレス性によるスケーラビリティ、および習得の容易さです。一方、オーバーフェッチやアンダーフェッチ、リアルタイム通信への制限といった課題があり、特定のユースケースでは GraphQL、gRPC、WebSocket などの選択肢も検討する価値があります。

REST は、その設計原理の優雅さと実装の単純さから、今なお Web API 設計の標準的な手法であり、マイクロサービス、クラウドコンピューティング時代においても重要な役割を果たし続けています。

📖 English version available / 英語版も利用可能
Read the English version of this article