REST APIクライアントのメソッド名のガイドラインの一例

ClientクラスにHTTPリクエストを送るインスタンスメソッドを定義するとして、このメソッドにどういう名前を付けるかという話。

メソッド名には動詞を利用する

メソッド名を動詞から始めるべきか、名詞から始めるべきか。ここにはメソッドの呼び出しをクエリと捉えるか、コマンドと捉えるか、という判断がある。メソッド名を名詞から始める場合はよりクエリ寄り、動詞から始める場合はコマンド寄りに捉えていると言える。ここではコマンド寄りに捉えて動詞を利用することにする (注釈: 厳密にはコマンドは値を返さないことが多いのでコマンド"寄り"と呼んだ)。

HTTPリクエストのメソッドごとに異なる動詞を使う

メソッド名を動詞から始めるとして、どの動詞を使うべきか。全てのメソッドは何らかのHTTPリクエストを送る訳だから、そのメソッドを実行することで発行されるHTTPリクエストのメソッドを動詞の選択材料に利用することにする。一例として、GETならget、POSTならpost、PATCHならupdate、PUTならput、DELETEならdeleteという動詞を利用するというルールが考えられる。

問い合わせるリソースの単複で異なる動詞を使う

GETリクエストとして提供されているAPIを、複数のリソースを問い合わせるものと、単一のリソースを問い合わせる、というパターンで分ける。一例として、複数のリソースを返すものにlist、単一のリソースを返すものにgetを使うというルールが考えられる。

対象リソース名を目的語に含む

対象とするリソース名を目的語としてメソッド名に利用する。例えば GET /usersにはlist_users、DELETE /users/:idにはdelete_userを利用する。

ネストしたリソースの名前は目的語のprefixにする

GET /users/:user_id/gists というネストしたURLを GET /gists をどう区別するかという問題がある。同じ list_gistsで引数によってリクエスト先を変更するという仕様にもできるが、1つのエンドポイントには1つのメソッドが対応する、というルールを守った方が理解しやすいと考える。この場合、GET /users/:user_id/gistsにはlist_user_gists、GET /gistsにはlist_gistsを対応させる。

on/offのスイッチを操作する場合は別の動詞を用意する

リクエストボディを送らずレスポンスも受け取らないパターンのAPIがある。例えばGitHubの提供しているGistにスターを付けたり外したりするAPIは、(PUT|DELETE) /gists/:id というエンドポイントになっている。スターというリソースを考えて「put_gist_star」「delete_gist_star」という風にしても良いが、ここでは (un)starという動詞を考えて「star_gist」「unstar_gist」という風に扱う。