RESTful API - gosaaan1/hokulea-garage GitHub Wiki

RESTful APIとは

REST API（Representational State Transfer API）は、Webサービス間の通信を行うための設計スタイルです。

RESTful API設計に関する基本的なポイント

  1. リソースの設計: RESTful APIでは、リソース（データのエンティティ）を名詞で表現し動詞は避けるようにします。リソースに対する操作をHTTPメソッド（GET, POST, PUT, DELETE）で表現します。

    • 例: ユーザー情報を扱う場合、/usersエンドポイントを使用します。顧客リソースは /customers、特定の顧客は /customers/5 という風にします。 補足：顧客のIDに推測可能な値（整数の連番）を割り当てるのはセキュリティ上望ましくないらしく、UUIDを使う方が良いとのこと。
    • 例: 新しい注文を作成するには POST /orders、既存の注文を更新するには PUT /orders/99 とします。

  2. ステートレス性: RESTful APIはステートレスであるべきです。つまり、各リクエストは独立しており、サーバーはクライアントの状態を保持しません。これにより、スケーラビリティとシンプルさが向上します。

  3. HTTPステータスコードの使用: 適切なHTTPステータスコードを使用して、リクエストの結果をクライアントに伝えます。

    • 例: 成功したリクエストには200（OK）、リソースが見つからない場合には404（Not Found）を返します。

  4. エラーハンドリング: エラーメッセージは明確で詳細なものにし、クライアントが問題を理解しやすいようにします。例えば、バリデーションエラーの場合、どのフィールドが問題なのかを具体的に示します。

これらのポイントを押さえることで、使いやすく、メンテナンスしやすいAPIを設計することができます。

アーキテクチャ

RESTful APIの設計において、フィールディング博士が提唱した要件や制約は以下の通りです：

  • クライアント-サーバーアーキテクチャ: クライアントとサーバーを分離し、クライアントはユーザーインターフェースを管理し、サーバーはデータストレージとビジネスロジックを管理します。
  • ステートレス: 各リクエストは独立しており、サーバーはクライアントの状態を保持しません。これにより、スケーラビリティが向上します。
  • キャッシュ可能: レスポンスはキャッシュ可能であるべきです。適切なキャッシュ制御を行うことで、パフォーマンスが向上します。
  • 統一インターフェース: 一貫したインターフェースを提供することで、システムの独立した進化を可能にします。
  • 階層システム: システムは階層構造を持ち、各層は他の層の詳細を知らずに機能します。

これらの要件や制約を守ることで、スケーラブルで効率的なWeb APIを設計することができます。