RESTとは
REpresentational State Transferの略で、分散型システムにおける複数のソフトウェアを連携させるのに適した設計原則の集合、考え方のこと
RESTの原則
主に以下の4つの原則から成る
- アドレス可能性(Addressability)
- 提供する情報がURIを通して表現できること。全ての情報はURIで表現される一意なアドレスを持っている
- ステートレス性(Stateless)
- HTTPをベースにしたステートレスなクライアント/サーバプロトコルである
- セッション等の状態管理はせず、やり取りされる情報はそれ自体で完結して解釈できる
- 接続性(Connectability)
- 情報の内部に、別の情報や(その情報の別の)状態へのリンクを含めることができる
- 統一インターフェース(Uniform Interface)
- 情報の操作(取得、作成、更新、削除)は全てHTTPメソッド(GET、POST、PUT、DELETE)を利用する
REST API
- RESTの原則に則って構築されたWebシステムのHTTPでの呼び出しインターフェース
- HTTPメソッド, パラメータ, URI, レスポンス形式等の項目に該当する
REST APIのメリット
- URIに規律が生まれ、APIを利用する開発者が把握しやすく実装しやすい
- ブラウザへURIを入力するだけでリソースの参照ができる
- ステートレスであり、サーバ・クライアント間で何も共有しないため、負荷に応じたスケーラビリティを向上することができる
- HTTP標準のメソッドを使うことで、シンプルかつ一貫性のあるリクエストが円滑に行うことができる
リソース設計
- 何をリソースとするか決める。APIの利用者がどのようなリソースを必要としているか、そのリソースをどのように利用するかといったユースケースを考えながらリソースを抽出する
- 抽出したリソースに対して、どのようなCRUD操作が必要かを検討する
- リソース間の従属関係(親子関係)を明確にする
- リソースの各項目のデータ型の定を行う
- リソース定義を明文化する
HTTPメソッド
クライアントが行いたい処理をサーバに伝えるという役割を担い、その種類は以下の9つ
- GET
- リソースの取得
- POST
- 子リソースの作成, リソースへのデータ追加, その他処理
- PUT
- リソースの更新, リソースの削除
- DELETE
- リソースの削除
- HEAD
- リソースのヘッダ (メタデータの取得)
- OPTIONS
- リソースがサポートしているメソッドの取得
- TRACE
- プロキシ動作の確認
- CONNECT
- プロキシ動作のトンネル接続への変更
- PATCH
- リソースの部分的な変更
CRUD
以下をCRUDとし、これらは基本的にCreate, Read, Update, Deleteにより満たすことができる
- Create（作成）
- メソッド : POST/PUT
- Read（読み込み）
- メソッド : GET
- Update（更新）
- メソッド : PUT
- Delete（削除）
- メソッド : DELETE
PUT？ POST？
PUTもPOSTもCreate（リソースの作成）に当たるが、冪等性から使い分けることができる
- PUT: リソースの作成、リソースの置換
- リソース名を指定して作成または更新をかけるメソッド
- POST: リソースの作成
- Idempotent（冪等）な操作で、何度やっても同じ結果になるような処理
設計指針ポイント
- PUT
- 更新成功の場合 → 204 No Content
- クライアントにとって思い通りの結果になったということなので、中身は重要ではなく204で十分
- 更新成功の場合 → 204 No Content
- DELETE
- 成功時 → 204 No Content
- リソースがないので204が最適
- 成功時 → 204 No Content
- 失敗した時
- 4xxは通知することでクライアントまたはユーザが反応できる可能性があるときに利用する
便利ツール
APIのテストでは、「REST Client （Chrome Extension）」が便利