APIクライアントのメソッド名のガイドラインの一例2014年09月21日ClientクラスにHTTPリクエストを送るインスタンスメソッドを定義するとして、このメソッドにどういう名前を付けるかという話。メソッド名には動詞を利用するメソッド名を動詞から始めるべきか、名詞から始めるべきか。ここにはメソッドの呼び出しをクエリと捉えるか、コマンドと捉えるか、という判断がある。メソッド名を名詞から始める場合はよりクエリ寄り、動詞から始める場合はコマンド寄りに捉えていると言える。厳密にはコマンドは値を返さないことが多いのでコマンド"寄り"と呼んだ)。HTTPリクエストのメソッドごとに異なる動詞を使うメソッド名を動詞から始めるとして、どの動詞を使うべきか。全てのメソッドは何らかのHTTPリクエストを送る訳だから、そのメソッドを実行することで発行されるHTTPリクエストのメソッドを動詞の選択材料に利用することにする。一例として、GETならget、POSTならpost、PATCHならupdate、PUTならput、DELETEならdeleteという動詞を利用するというルールが考えられる。問い合わせるリソースの単複で異なる動詞を使うGETリクエストとして提供されているAPIを、複数のリソースを問い合わせるものと、単一のリソースを問い合わせる、というパターンで分ける。一例として、複数のリソースを返すものにlist、単一のリソースを返すものにgetを使うというルールが考えられる。対象リソース名を目的語に含む対象とするリソース名を目的語としてメソッド名に利用する。/users/:idにはdeleteuserを利用する。区別するかという問題がある。listgistsで引数によってリクエスト先を変更するという仕様にもできるが、1つのエンドポイントには1つのメソッドが対応する、というルールを守った方が理解しやすいと考える。/gistsにはlistgistsを対応させる。on/offのスイッチを操作する場合は別の動詞を用意するリクエストボディを送らずレスポンスも受け取らないパターンのAPIがある。いうエンドポイントになっている。(un)starという動詞を考えて「stargist」「unstargist」という風に扱う。