REST APIを知る

はじめに

この記事では、現代のWebアプリケーションで広く使われているREST APIについて、RESTの基本原則や設計の基本ルールを紹介します。

REST APIとは

• REST(Representational State Transfer)：リソース指向のWebサービスの設計原則
• API(Application Programming Interface)：外部から機能やデータにアクセスするための仕組み

REST原則

①クライアント・サーバー構造

• クライアント（データ利用側）とサーバー（データ提供側）が明確に分かれている

②ステートレス

• サーバーがクライアントの状態を保存せず、各リクエストは独立している
  • メリット
    • リクエストが独立しているため、追加のサーバーを導入して容易に負荷分散できる
    • 障害が発生したリクエストのみリカバリーすればよいため、容易に障害復旧できる
  • デメリット
    • ステートフル（サーバーがクライアントの状態を保持）と比べてリクエストデータに重複がある

③キャッシュ制御

• レスポンスデータをキャッシュ可能
  • メリット
    • リソース効率の向上
  • デメリット
    • 古いデータを取得する可能性がある

④階層化システム

• システムは複数の階層で構成され、各階層は独立して機能する
  • メリット
    • 各システムが分離されているので柔軟性と拡張性が向上
  • デメリット
    • システム間のデータ処理にオーバーヘッド発生

⑤コードオンデマンド

• クライアントにコードをダウンロードして提供できる
  • メリット
    • 容易にクライアントの機能追加
    • クライアントのリソースを利用できるのでサーバー負荷軽減
  • デメリット
    • 複数のブラウザ（Chrome, Edge）のように評価環境が異なる

⑥統一インターフェース

リソースの識別

• 各リソースはURIを用いて識別される
  • （例）/users（ユーザー情報の一覧）

リソースの操作

• リソースのある断面情報を利用してデータを操作する
  • （例）Authorization（認証情報）

自己記述メッセージ

• レスポンスヘッダーから内容（メタ情報）の意味が理解できる
  • （例）Content-type（メディアタイプ）

HATEOAS

• リソース間の関連や状態遷移に関する情報が含まれる
  • （例）次のページへのリンク

REST API設計の基本

URI設計

URI(Uniform Resource Identifier): リソースを識別するための文字列

ルール

• リソースを表現
  • （例）o:/users, x:getUsers
• 自然と理解できる名詞
  • （例）o:/users, x:/u
• リソース間の関係性を表現するために階層構造を使用
  • （例）/users/123/orders
• 複数形を使用
  • （例）/users
• 小文字を使用
  • （例）o:/users, x:/USERS
• -を使用（_を使用しない）
  • （例）o:/favorite-users, x:/favorite_users

URIとHTTPメソッドの組み合わせ

usersをリソースとしたCRUD操作の例です。

name	URI	HTTP method
ユーザーの新規登録	/users	POST
ユーザーの取得（複数件）	/users	GET
ユーザーの取得（1件）	/users/1	GET
ユーザーの更新	/users/1	PUT
ユーザーの削除	/users/1	DELETE

クエリとパスの使い分け

• 省略可能か？
  • YES→クエリパラメータ
    • （例）ユーザーを検索条件で検索: /users?name=8tako8tako8（nameがなくても検索可能）
  • No→パスパラメータ
    • （例）特定のユーザーの注文一覧: /users/1/orders（user_id: 1は省略できない）

まとめ

REST APIの基本原則と設計の基本ルールを紹介しました。今回はレスポンス設計やOpenAPI(Swagger)について含めていないので、機会があればまとめてみます。