What's the correct "RESTful" URL for an action that adds a child record to a parent record?
For example, if I wanted to provide a URL for adding a "comment" record to an "order" record, how should I format it?
My first thought was something like:
PUT http://example.com/order/12345/comment/add
I work in Django, which uses a similar pattern, so this seemed most intuitive. However, reading over some RESTful design guides like this one suggests that this might be bad practice, as they argue the "PUT" and "add" are redundant and therefore might create confusion.
Answers
I would do the following:
POST http://example.com/order/12345/comment
Answers
The put action and the add part of the url are redundant. But there is no hard rule on any of this. I see apis having that form, even from major vendors, and sometimes simply remark "The put action and the uri segment are redundant" Sometimes I say nothing at all and just call the endpoint. If I were writing an api, I would probably leave off the add part.
Answers
there are few points to make your request RESTful:
1) Use resources names in the URL in plural and not in a singular form (orders instead of order)
2) never use ACTION names in your URL such as (ADD) in "comment/add"
3) since you are adding a "NEW" comment without knowing any IDs of hands you should use POST request.
Finally, the URL I would recommend is:
HttpVerbs = POST
http://api.example.com/orders/12345/comments
That should add a new comment to your order#12345
Answers
There is no one-size-fits-all answer to your question. Rest URLs can be whatever you want them to be. At the end of the day, they are routes that get mapped to a method. I wouldn't worry too much about the "best" URL. I prefer to find a standard that works for me and then move on to bigger, more important things. As long as clients know what the URL is, they will be fine.