Modeling Actions as Resources

One idea I’ve internalized while designing APIs is that actions don’t always have to look like actions. Many actions are better off being actual resources. It feels intuitive and logical to define endpoints like: POST /subscriptions/:id/cancel POST /invoices/:id/pay It’s straightforward to build, easy for clients to use, and by itself it’s not inherently wrong. But again and again, I’ve noticed its limitations. When an action becomes a resource When you cancel a subscription, there’s a reason. Easy: just add a reason field to the POST body. But a user can also change their mind and withdraw the cancellation, keep the subscription for a few months, and then cancel again. When you store status: "canceled" and reason: "too expensive" in your subscriptions database table, and the user withdraws the cancellation… what do you do with this information? Do you just throw it away? It’s valuable information! It’s also useful to be able to list all cancellation attempts of a user. It’s good…