Web APIのインタフェースを定義する際に決めなければならない点は以下になります。
- エンドポイントURI
- HTTPメソッド
- クエリパラメータ
エンドポイントURIの定義
ROA(Resource Oriented Architecture)におけるリソースは、URIを持つ必要があります。
エンドポイントURIとは、個々のリソースの所在を表すURIです。
前回に引き続き、本記事ではブログポストのリソースの扱いを題材にしていきます。
（オリジナルの記事ではメールのドメインリソースを題材としています）
すでに存在するリソースを返すエンドポイント
- GETメソッドでアクセスできる
- リソースの表現はapplication/json形式
- /api/posts：複数のpostsリソースを取得（コレクションリソース）
- /api/posts{/posts_id}：単一のpostsリソースを取得
- /api/posts{/posts_id}/comments{/id}：ポストに関連するコメントを取得する（エントリリソース）
新しいリソースを作成するエンドポイント
- POSTメソッドでアクセスできる
- リソースの表現はapplication/json形式
- /api/posts：新しいpostsリソースを作成
すでに存在するリソースを削除するエンドポイント
- DELETEメソッドでアクセスできる
- 削除が成功した場合は204 No Contentで応答する
- /api/posts{/posts_id}：単一のpostsリソースを削除
HTTPメソッドの選び方
RESTにおいてよく用いられるHTTPメソッドは次の4つです。
- GET（リソースの取得）
- POST（リソースの作成）
- PUT（リソースの更新）
- DELETE（リソースの削除）
POSTを利用するケース
a. コレクションリソースに対して新規のエントリリソースを追加
b. 既存のリソースに対して状態を追加
c. オーバーロードPOST
aとbが一般的な利用方法です。
cのオーバーロードは、「ROAの用途では表現しきれないインターフェースを持つもの全般を表現するために用いる手法」です。具体的には、リソースの差分更新などに使用されます。
PUTを利用するケース
a. 既存のエントリリソースを更新
b. 新規のエントリリソースを（明示的に）追加
aは既存のリソースに対する差分更新ではなく置き換えだという点が重要です。PUTメソッドによる更新の際は、置き換えるべきリソースの完全な表現をリソースに含める必要があり、一部分だけを更新することはできません。完全な表現が含まれるからこそ、PUTメソッドの冪等性があるといえます。
差分更新については、PATCHという新しいHTTPメソッドがRFC5789で提案されており、Rails4でも採用されています。
コレクションとクエリパラメータ
コレクションリソースを取得する場合、エントリを何らかのリストとして表現する必要があります。こういったコレクションに対しては、取得件数や並び順、検索条件などを取得時に指定したいことがあります。
クエリパラメータが必要なケース
コレクションリソース全体を取得すると膨大な量になってしまうような場合には、ページネーションが必要となります。
ページネーションのためには、以下のようなクエリパラメータが必要です。
- コレクション取得の開始位置(OFFSET)
- コレクションの最大取得件数(LIMIT)
- コレクションのソートフィールド(ORDER BY)
- コレクションの並び順(ASC/DESC)