Skip header to navigation
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 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 information for someone like a customer support agent to see the user’s history during a support inquiry. “Listing cancellations” sounds a lot like a resource.
It’s similar for paying an invoice: a payment can fail, it’s more like a payment attempt. Also, storing this information in the parent resource is kinda… ugly. It turns into situations like these:
It often results in fields that are nullable (like failure_reason in the example above), but are never null when the status is "payment_failed". It’s a weird API contract: it’s not self-explanatory and you have to explain the behavior to an API consumer. The API is mashing two different concepts into a single resource.
So instead of modeling these actions as verbs attached to a resource, I now almost always reach for modeling the action as a proper resource:
All action-related properties are bundled inside one resource, no weird nullables. And most importantly, you don’t lose the history in your database. You can just list them all:
I also usually model them as top-level resources, and not nested resources like /subscriptions/:id/cancellations. It might look handy at first sight, but having it as a top-level resource allows you to list all cancellations, or add more complex filters as URL parameters that aren’t possible as a subresource.
A few times in this post, I’ve emphasized that this pattern is helpful almost always.
Last week I added a friend request feature to an API, so two users can connect with each other and become friends:
After designing everything in the API as resources, it kinda hurt to define these action endpoints. But what’s the alternative?
POST /friend_request_responses?
Accepting or ignoring a friend request isn’t a useful independent identity by itself. You usually can’t decline a friend request, and then a bit later accept it again. The user would instead send a new friend request, and not update an existing one.
In my mind, I ask myself “do I want to refer to this action later?” If so, I model it as a resource.
It could also be:
However, I don’t like an API surface where you change a field and it kicks off some side effects. Accepting a friend request will create a new friendship resource between both users, it will send out a notification… that’s more than simply updating some data.
In comparison, when a user updates their profile:
…that just changes the name that’s shown in the app. It doesn’t kick off a chain of user-facing side-effects.
As I mentioned above, having resources for these actions means that we can view their history. That’s not only useful for support folks, but also for us developers.
You can use it to trace events in your system, see how things progressed, and debug without painfully going through logs or by reading the code and guessing how a bug might have happened. You can store outcomes of a long-running background action, error messages, retry attempts… the stuff you would usually just log so you can debug errors when they might happen.
And you can turn complex processes, where one action fans out into multiple resources, into straightforward logic. For example:
Now, when a user complains that they didn’t receive a notification, you can go into the database and see what’s up: was a Notification created? How many devices are registered for the user? Was a Push Notification created for each device? Was there an error?
And it doesn’t stop there:
Are actions as resources premature optimization? Saying “it might be helpful in the future” sounds a lot like YAGNI1. So, should you first build the action endpoint, and later turn it into a resource?
I don’t think so. It isn’t speculative future-proofing when the action already has domain data that I care about: The cancellation reason already exists. The payment failure already exists. Putting it into a resource decides where this information belongs, not whether it’s needed.
These days, my rule of thumb is simple: does the action have information on its own? Does it have a lifecycle? Is it something I want to inspect later? Then it’s a resource. If it’s just a state transition, I’ve learned not to force it.
It’s a small shift in how I model APIs, and it has consistently made the systems behind them easier to understand, extend, and debug.
Anyway, time for a walk.
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 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 information for someone like a customer support agent to see the user’s history during a support inquiry. “Listing cancellations” sounds a lot like a resource.
It’s similar for paying an invoice: a payment can fail, it’s more like a payment attempt. Also, storing this information in the parent resource is kinda… ugly. It turns into situations like these:
It often results in fields that are nullable (like failure_reason in the example above), but are never null when the status is "payment_failed". It’s a weird API contract: it’s not self-explanatory and you have to explain the behavior to an API consumer. The API is mashing two different concepts into a single resource.
So instead of modeling these actions as verbs attached to a resource, I now almost always reach for modeling the action as a proper resource:
All action-related properties are bundled inside one resource, no weird nullables. And most importantly, you don’t lose the history in your database. You can just list them all:
I also usually model them as top-level resources, and not nested resources like /subscriptions/:id/cancellations. It might look handy at first sight, but having it as a top-level resource allows you to list all cancellations, or add more complex filters as URL parameters that aren’t possible as a subresource.
A few times in this post, I’ve emphasized that this pattern is helpful almost always.
Last week I added a friend request feature to an API, so two users can connect with each other and become friends:
After designing everything in the API as resources, it kinda hurt to define these action endpoints. But what’s the alternative?
POST /friend_request_responses?
Accepting or ignoring a friend request isn’t a useful independent identity by itself. You usually can’t decline a friend request, and then a bit later accept it again. The user would instead send a new friend request, and not update an existing one.
In my mind, I ask myself “do I want to refer to this action later?” If so, I model it as a resource.
It could also be:
However, I don’t like an API surface where you change a field and it kicks off some side effects. Accepting a friend request will create a new friendship resource between both users, it will send out a notification… that’s more than simply updating some data.
In comparison, when a user updates their profile:
…that just changes the name that’s shown in the app. It doesn’t kick off a chain of user-facing side-effects.
As I mentioned above, having resources for these actions means that we can view their history. That’s not only useful for support folks, but also for us developers.
You can use it to trace events in your system, see how things progressed, and debug without painfully going through logs or by reading the code and guessing how a bug might have happened. You can store outcomes of a long-running background action, error messages, retry attempts… the stuff you would usually just log so you can debug errors when they might happen.
And you can turn complex processes, where one action fans out into multiple resources, into straightforward logic. For example:
Now, when a user complains that they didn’t receive a notification, you can go into the database and see what’s up: was a Notification created? How many devices are registered for the user? Was a Push Notification created for each device? Was there an error?
And it doesn’t stop there:
Are actions as resources premature optimization? Saying “it might be helpful in the future” sounds a lot like YAGNI1. So, should you first build the action endpoint, and later turn it into a resource?
I don’t think so. It isn’t speculative future-proofing when the action already has domain data that I care about: The cancellation reason already exists. The payment failure already exists. Putting it into a resource decides where this information belongs, not whether it’s needed.
These days, my rule of thumb is simple: does the action have information on its own? Does it have a lifecycle? Is it something I want to inspect later? Then it’s a resource. If it’s just a state transition, I’ve learned not to force it.
It’s a small shift in how I model APIs, and it has consistently made the systems behind them easier to understand, extend, and debug.
Anyway, time for a walk.
GET /notificationsPATCH /friend_requests/:id
{"response": "accept"}
GET /notificationsPATCH /friend_requests/:id
{"response": "accept"}
send a user a friend request:
POST /friend_requests { sender, recipient }
to respond to the friend request:
POST /friend_requests/:id/accept
POST /friend_requests/:id/ignore
send a user a friend request:
POST /friend_requests { sender, recipient }
to respond to the friend request:
POST /friend_requests/:id/accept
POST /friend_requests/:id/ignore
{
"type": "invoice",
"status": "payment_failed",
"failure_reason": "insufficient funds",
"payment_method": { /* ... */ }
}
// or
{
"type": "invoice",
"status": "paid",
"failure_reason": null,
"payment_method": { /* ... */ }
}
{
"type": "invoice",
"status": "payment_failed",
"failure_reason": "insufficient funds",
"payment_method": { /* ... */ }
}
// or
{
"type": "invoice",
"status": "paid",
"failure_reason": null,
"payment_method": { /* ... */ }
}
POST /subscription_cancellations
POST /payment_attempts
POST /subscription_cancellations
POST /payment_attempts
PATCH /user_profiles/me
{"display_name": "Robinson Crusoe"}
PATCH /user_profiles/me
{"display_name": "Robinson Crusoe"}
GET /subscription_cancellations?subscription=sub_123
GET /subscription_cancellations?user=usr_xyz
GET /payment_attempts?invoice=inv_000
GET /subscription_cancellations?subscription=sub_123
GET /subscription_cancellations?user=usr_xyz
GET /payment_attempts?invoice=inv_000