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...