REST APIとは：HTTPメソッドとモバイルアプリにおける動作原理

REST APIとは？

REST API（Representational State Transfer API）は、2000年にロイ・フィールディングが博士論文で提唱したアーキテクチャスタイルです。ネットワークプロトコルを設計するための一連の制約と原則を定義しています。これらの制約に準拠したAPIはRESTfulと呼ばれます。RESTはプロトコルや標準ではありません — 既存のプロトコル（主にHTTP）を使用してクライアントとサーバー間でデータを交換するアーキテクチャアプローチです。

RESTの核となる考え方はリソース指向アーキテクチャです。サーバー上のメソッドを呼び出す代わりに（SOAPやRPCのように）、クライアントはリソースを操作します：リストを取得したり、新規作成したり、更新または削除したりします。各リソースはドメインエンティティ（ユーザー、注文、商品、記事）です。リソースには状態があり、標準化された形式（通常はJSON）でクライアントに送信されます。サーバーはリクエスト間でクライアントの状態を保存しません — これがステートレス（stateless）の原則であり、RESTの主要な要件です。

REST APIの主な特性：

• Stateless — クライアントからの各リクエストには処理に必要なすべての情報が含まれる
• Cacheable — サーバーの応答はキャッシュ可能かどうかを明示的に示す必要がある
• Layered system — アーキテクチャには中間サーバー、ロードバランサー、プロキシを含めることができる
• Uniform interface — HTTPメソッド、URL、ステータスコードを介した統一されたインターフェース

RESTアーキテクチャの原則

RESTはフィールディングによって定式化された6つのアーキテクチャ上の制約に基づいています。これらの制約への準拠により、スケーラビリティ、パフォーマンス、統合の容易さが保証されます。各原則は分散システムの特定の問題 — キャッシングの必要性からセキュリティ要件まで — を解決します。各原則を詳しく見ていきましょう。

Uniform Interfaceの原則にはさらに4つのサブ制約が含まれます：URIによるリソース識別、表現によるリソース操作、自己記述的なメッセージ、HATEOAS（アプリケーション状態のエンジンとしてのハイパーメディア）。最後のサブ制約は実際にはしばしば無視されます — ほとんどの現代的なREST APIはHATEOASを完全には実装しておらず、そのようなAPIが“本当に”RESTfulかどうかの議論につながっています。

Statelessの原則はスケーリングにとって最も重要なものの一つです。サーバー側にセッションがないということは、任意のサーバーインスタンスが任意のリクエストを処理できることを意味します。これにより水平スケーリングが簡単になります：ロードバランサーの背後に新しいサーバーを追加するだけです。モバイルアプリケーションにとって、ステートレスはリクエストを任意のCDNサーバーに送信できることも意味し、これはグローバルな可用性にとって重要です。

RESTにおけるHTTPメソッド

REST APIの各HTTPメソッドはリソースに対する特定の操作に対応します：GETは読み取り、POSTは作成、PUTは完全更新、PATCHは部分更新、DELETEは削除です。メソッドの冪等性は重要な特徴です：GET、PUT、DELETEは冪等（繰り返し実行しても同じ結果）、POSTとPATCHは冪等ではありません。これは、リクエストがサーバーに到達したかどうかクライアントが不明な場合のネットワークエラー処理に重要です。

• GET — リソースまたはリソースリストの取得。冪等、サーバーの状態を変更しない
• POST — 新しいリソースの作成。非冪等、呼び出しごとに新しいリソースを作成する
• PUT — リソースの完全な置き換え。冪等、最初以降の繰り返し呼び出しは状態を変更しない
• PATCH — リソースの部分更新。部分的に冪等（実装に依存）
• DELETE — リソースの削除。冪等、繰り返し削除は404を返し、エラーにはならない

HTTPステータスコードはREST APIの不可欠な部分です。各コードには特定の意味があります：成功したGETには200 OK、POSTには201 Created、応答ボディなしのDELETEには204 No Content、無効なデータには400 Bad Request、認証不足には401 Unauthorized、リソース不在には404 Not Found。ステータスコードを適切に使用することで、APIは自己文書化され、デバッグが容易になります。

データ形式：JSONとその他

JSON（JavaScript Object Notation）はREST APIにおけるデータ転送の主要な形式です。その人気は、シンプルさ、人間可読性、JavaScriptでのネイティブサポートによるものです。JSONはContent-Type: application/jsonヘッダーとともに送信されます。代替手段には、XML（冗長で古くなりつつある）、YAML（設定に便利でAPIにはあまり一般的でない）、Protocol Buffers（バイナリ形式で高負荷システムに効率的）があります。

REST APIにおけるJSONオブジェクトの構造には通常、id、typeフィールドとリソース属性が含まれます。コレクションには、ページネーションメタデータを含むJSON配列が使用されます。現代のREST APIは、応答検証のためにJSON:API仕様（jsonapi.org）またはJSON Schemaに従います。統一されたデータ形式を使用することで、クライアントライブラリの開発とドキュメント生成が簡素化されます。

ユーザーリストのJSON応答例：

{
    "data": [
        {
            "id": 1,
            "name": "アンナ・ペトロワ",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

データ転送形式の選択はモバイルアプリケーションのパフォーマンスに影響します。JSONはGZIPで70〜80%圧縮され、ほとんどのシナリオで許容可能です。大量のデータ（ストリーミング、ゲーム）を扱うリアルタイムアプリケーションでは、バイナリプロトコルに切り替えるか、Protocol Buffersと組み合わせてWebSocketを使用することをお勧めします。

REST APIリクエストの例

モバイルアプリケーション側でのREST APIの実践的な例を見てみましょう。例として、オンラインストアで注文を扱うAPIを取り上げます。各HTTPメソッドについて、リクエストと期待されるサーバー応答を示します。これらの例は、モバイル開発で使用される典型的なRESTful API構造を示しています。

GET — 注文リストの取得

ページネーション付きで全ユーザー注文を取得するリクエスト。応答には注文オブジェクトの配列とページナビゲーション用のメタ情報が含まれます。pageパラメータとper_pageパラメータはクエリ文字列で渡されます。

// REST APIのためのRetrofitインターフェース
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — 新規注文の作成

POSTリクエストによる新規注文の作成。サーバーは201 Createdステータスと作成されたオブジェクトを応答ボディで返します。重要：作成は特定のリソースではなく、コレクション/api/v1/ordersに対して行われます — これが標準的なRESTfulパターンです。

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// リクエストボディの例
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — 注文の削除

リソースの削除は特定の注文URLに対してDELETEメソッドで行われます。削除成功時は204 No Contentを返します。DELETEの冪等性により、同じURLへの繰り返しリクエストは404 Not Foundを返し、クライアント側で適切に処理されます。

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// ViewModelでの使用
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

これらの例は、RetrofitとKotlin Coroutinesを使用したAndroid側での典型的なREST API実装を示しています。iOSアプリケーションでは、URLSessionまたはAlamofireライブラリがCodableプロトコルと組み合わせて同様の役割を果たします。REST APIの構造はプラットフォームに関係なく同じです — リクエストの実行方法のみが異なります。

RESTful API設計：実践的な推奨事項

高品質なRESTful APIを設計するには、開発者にとって直感的なAPIにするための規約に従う必要があります。リソースは複数形の名詞（/users、/orders、/products）で命名し、HTTPメソッドは操作を反映し、URLはネスト階層を表現する必要があります。エラーはHTTPステータスだけでなく、コードとメッセージを含む標準化されたJSONを返す必要があります。これらの規約に従うことで、新しい開発者の参入障壁が低くなり、統合が簡素化されます。

• リソースの命名 — 複数形、kebab-case：/api/v1/user-orders（/api/v1/getUserOrdersではない）
• フィルタリングとソート — クエリパラメータ経由：?status=active&sort=created_at:desc
• ページネーション — 大規模セットにはカーソルベース、小規模にはページベース
• バージョニング — URL（/api/v2/）またはAccept-Versionヘッダー経由
• エラー — 統一形式：{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• レート制限 — X-RateLimit-RemainingとRetry-Afterヘッダー

REST APIを設計する際の一般的な間違いは、過度なリソースのネストです。/users/1/orders/5/items/3の代わりに、クエリパラメータを使用したフラットな構造 /items?order_id=5&user_id=1 を使用する方が良いでしょう。これによりキャッシングが簡単になり、サーバー上で長いパスを維持する必要がなく、ドキュメント化も容易になります。フラットなアーキテクチャは、将来的にGraphQLに移行する際のグラフベースのクエリとの互換性も高くなります。

REST APIのセキュリティは、認証（JWT、OAuth 2.0）とリソースレベルでの認可によって実装されます。各リクエストは、ユーザーが要求されたリソースにアクセス権を持っているかを確認する必要があります。HTTPSは必須です — 暗号化がないと、トークンやデータが平文で送信されます。モバイルアプリケーションでは、安全なトークン取得のためにPKCE（Proof Key for Code Exchange）付きのOAuth 2.0を使用することを推奨します。

バージョニングとキャッシング

REST APIのバージョニングは、変更時の後方互換性のために必要です。最も一般的なアプローチは次のとおりです：URLにバージョンを含める（/api/v1/orders）、ヘッダーにバージョンを含める（Accept: application/vnd.myapi.v1+json）、クエリパラメータにバージョンを含める（?api_version=1）。URLバージョニングはログやドキュメントで明示的に確認できるため、最も一般的な方法です。ただし、リソースごとに単一のURLを持つというRESTの原則に違反します。

REST APIにおけるキャッシングは、HTTPヘッダーCache-Control、ETag、Last-Modifiedを介して実装されます。キャッシュ可能とマークされたGETリクエストは、サーバーに問い合わせずにブラウザキャッシュやプロキシキャッシュから提供できます。モバイルアプリケーションにとって、キャッシングは特に重要です — データ使用量を削減し、接続状態が悪い場合でも以前に読み込んだデータの表示を高速化します。ETagは応答コンテンツのハッシュであり、クライアントがIf-None-Matchで送信し、データが変更されていない場合にサーバーは304 Not Modifiedを返します。

REST APIの現代的な代替手段には、GraphQL（柔軟なクライアント側データ取得）とgRPC（マイクロサービス向けHTTP/2上のバイナリプロトコル）があります。しかし、RESTはそのシンプルさ、普遍性、そして広範なツールサポートにより、公開APIの主要な標準であり続けています。RESTと代替手段の選択は、プロジェクトの具体的な要件（クエリの複雑さ、データ量、リアルタイム更新の必要性）によって異なります。