『Web API デザインの鉄則』第3章 インタフェース設計

WEB+DB PRESS Vol.82

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)

コメントを残す