以下のようにするのが最善だと思いました。
例
PUT /companies/{id}/count/reset
理由
- URLによるリソース表現と概念的な差異が大きい
- CRUD以外の操作
- リセットは同じリクエストを何回行っても同じ結果になる（べき等）
背景
業務でカウントをリセットするAPIを実装しました。
POST /companies/{id}/reset_count
このカウントを管理しているテーブルはPATCHでも更新を受けつけていたのですが、今回はリセットというアクションを表現する方が良いと考え、別でエンドポイントを作成しました（本来だとURIはリソース名の名詞で表現することが推奨されています）。
PATCH /companies/{id}
今回の判断が妥当だったか改めて考えます。
URIにアクションを明示的に記述する
Githubのリポジトリでスターをつける、解除するのリクエストを見ると以下のようになっていました。
Githubリポジトリにスターを付ける：https://github.com/eslint/eslint/star
Githubリポジトリからスターを解除する：https://github.com/eslint/eslint/unstar
以下で説明されていました。
Use POST for operations that are not CRUD, such as triggering an action on the server
CRUD以外の操作（サーバー上でアクションをトリガーするなど）にはPOSTを使用する
引用
また、URLによるリソース表現と概念的な差異が大きい場合にPOSTが推奨されているということが以下で書かれていました。
他だとPUTメソッドで定義しているものがありました。
resetをURLに入れているエンドポイントがありましたので紹介します。
PUT:https://xxxx.backendless.app/api/counters/<counterName>/reset
同じリクエストを何回しても同じ結果になる（べき等）のでPOSTではなくPUTを使っているということがわかりました。
アクションをリソースの項目の1つとして扱う
こちらの記事で紹介されていました。
例として何かを有効化、無効化するようなアクションを挙げています。
対象となるboolean項目でアクティベートであるかという状態を扱って、そこに対してPATCHリクエストを投げます。
記事執筆当時のgistは以下のような設計になっていたそうです。
現在のgistを見ると先で紹介したパターンと同じようになっていました（gistの例）。
例）GitHub API
Gistにスターをつけるアクション：PUT /gists/:id/star
スターを解除するアクション： DELETE /gists/:id/star
まとめ
以下のようにするのが最善だと思いました。
PUT /companies/{id}/count/reset
理由
- URLによるリソース表現と概念的な差異が大きい
- CRUD以外の操作
- リセットは同じリクエストを何回行っても同じ結果になる（べき等）
参考