4

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!

Community
  • 1
  • 1
hajpoj
  • 13,299
  • 2
  • 46
  • 63

1 Answers1

3

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!

Community
  • 1
  • 1
Aseem Kishore
  • 10,404
  • 10
  • 51
  • 56
  • good point in terms of framing everything in terms of nouns instead of verbs. Your question and examples from github, facebook, etc were very helpful. Seems as though there is no standard way for these types of things. :/ – hajpoj Dec 06 '12 at 06:34