サーバのAPI設計について

Question

サーバのAPI設定についての質問です

REST APIというものを知り、とてもわかりやすくて良いなと思いました。
僕の理解は、以下の様です。

• データベース等からデータを検索する際にGETをつかう。
• データベース等にデータを登録する際にPOSTをつかう。
• データベース等からデータを削除する際にDELETEつかう。
• データベース等のデータを更新する際にPUTをつかう。
• それぞれに対して、複数形の名詞を使う
• idを指定する場合はhoges/:idとする

ここで質問なんですが、

• データベース等にアクセスせず、クライアントからのデータをサーバ側で加工し、

再度クライアント側へ返信するようなAPIの場合はどれを使うのが自然なんでしょうか。

• また、その際にapiの名前はどうするべきなのでしょうか。

例えば、凄く簡単な例だと、

• webページ（クライアント）に自然数を入力し、サーバ側に送信
• サーバ側は受け取った数をインクリメントする処理を実行する
• 結果をクライアントへ返信する

という例があったとして

この場合は{GET/POST/DELETE/PUT}のどれを使えば良いのでしょうか。
また、apiのエンドポイントはどのような名前にするべきでしょうか

Answer 1

HTTPリクエストを理論的に考えていく上では、冪等かどうか、ということがポイントとなってきます。

• 冪等なリクエスト（=何回リクエストしても同じ結果となるリクエスト） GET、PUT、DELETEなど
• 冪等でないリクエスト（=リクエストを繰り返すと意味が変わってくるもの）POST、PATCHなど

ということで、データベースなど状態を持たず、引数だけから値を返すのであればそれは冪等な操作なので、GETリクエストで構築するのが適当だと考えます（もちろん、パラメータが多すぎる、あるいはファイルも送る等の場合、GETで素直に流せませんが、それは別問題です）。

Comments

[metameta]

なるほど。
ありがとうございます。冪等であるかどうかが鍵なのですね。
わかりやすい説明をありがとうございます。

第二の質問について、apiの命名はどのようにすればいいかも、
よろしければ教えて頂けたらと思います。
僕の理解では、名詞の複数形を用いるのが、データベース等にアクセスする作法です。
今回のような、場合は、動詞＋名詞(increment_num)にするべきでしょうか。
それとも、動詞だけ(increment)。
もしくは、動詞＋型情報(increment_int)。
もし、正解がなければmiisumakun様の経験よりの回答を頂けたらと思います。