Question

So I want to know what are the best practices for doing actions on a object that doesn’t change the state of the object. If that doesn’t make sense bear with me, I think the tweet example explains what I am trying to say.

I understand the basics like described here:

What are the best/common RESTful url verbs and actions?

And how it works when updating/getting/deleting etc an object. But what about actions that don’t change the state of the object?

For example say we have a tweet object:

GET     `/tweets  (gets a list of tweets)
GET     `/tweets/new (gets a new page to create a new tweet)
POST    `/tweets (posts data to server to create new tweet)
GET     `/tweets/:id (get a single tweet)
GET    `/tweets/:id/edit (get a page to edit an exisiting tweet)
PUT    `/tweets/:id (put data to server to edit exisiting tweet)
Delete `/tweets/:id (delete an exisiting tweet)

This makes sense to me. But how do i form the URL for reply/ follow / retweet/ favorite, some of which don’t actually change the state of the tweet?

Should I do something like below?

POST   `/tweets/:id/reply       (post the reply message to the server)
POST    `/tweets/:id/follow     (post a boolean? yes I follow?)
POST    `/tweets/:id/retweet    (again post a boolean?)
POST    `/tweets/:id/favorite   (ditto)

Or do a

POST     `/tweet/:id/actions  (Do a post with the action I want to take as a parameter)

Or is there no “standard way”.
Anyways thanks for the help!

Answer 1

Great question.

As always, it helps to switch the framing to nouns instead of verbs. What are the resources you’re acting upon when you reply/etc.? And can those resources be fetched/addressed also?

In each of the cases you mentioned, I think the answer to the second question is yes. And in fact, Facebook’s Graph API and GitHub’s REST API both follow this approach.

E.g. for replying:

• GET /tweets/:id/replies to get a list of tweets that were in reply to the given one

• POST /tweets/:id/replies to create a new tweet in reply to the given one. The important part here is that success is a 201 Created w/ the Location header set to the created tweet’s endpoint, e.g. /tweets/1234.

• (Deleting a reply is then just deleting a tweet.)

Following/retweeting/favoriting are a bit trickier because the “nouns” are lightweight connections, and in fact, I just asked a Stack Overflow question for the “best” way to expose those:

RESTful API design: best way to CRUD lightweight connections?

You can see on that thread the specific way(s) you might implement following/retweeting/favoriting.

Hope this helps!