【API Design】動作を表す Custom Method
1
はじめに
Google が公開している API Design に関するドキュメントに，Custom Method というデザインパターンが紹介されています．
一般的な RESTful API の設計
例えば，記事を投稿するサイトを設計するとします．
一般的な RESTful API の設計ルールに則ると，記事（Article）の CRUD API は
# 一覧取得
GET /articles
# 単一取得
GET /articles/{id}
# 登録
POST /articles
# 更新
PUT /articles/{id}
# 削除
DELETE /articles/{id}
というようなパス設計になるとします．
若干特殊な要件
ここで，例えば，記事の作成時点では必ず Draft 状態で登録される，という仕様だったとします．
そうすると，記事を Publish する API が必要になります．
これを，RESTful な設計思想で考えると，「記事が公開された状態を作成する」という見方から，
POST /articles/{id}/published
というふうに定義することが多いと思います．
ただし，本来扱っているリソースは「記事」であり，状態の遷移をリソースの作成と捉えたくないと考える人もいます．
このとき，
PATCH /articles/{id}
を定義してis_published のみを true にするという考え方もあると思います．
ただし，公開状態を articles テーブルで管理しない場合，これも違和感があります
動作を定義する Custom Method
このような場合，以下のように動作を定義する方法があります
POST /articles/{id}:publish
このように，操作するリソースのパスの後ろに HTTP Method の範囲では表現できない操作(動詞)をコロンでつなげることで、リソースに対する特殊な操作を表現しようという考え方です。
メッセージの送信や承認、公開/アーカイブなどの操作を表現するのに大変便利です。