1

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.

Cerin
  • 60,957
  • 96
  • 316
  • 522

4 Answers4

3

I would do the following:

POST http://example.com/order/12345/comment
Riad Baghbanli
  • 3,105
  • 1
  • 12
  • 20
2

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.

Robert Moskal
  • 21,737
  • 8
  • 62
  • 86
  • But that's still preferable to `/order/12345/add_comment`, right? – Cerin May 27 '15 at 15:34
  • To my eyes /add_comment looks like some sort of entity (which is not your intention, so I might think it misleading as opposed to merely redundant). – Robert Moskal May 27 '15 at 15:39
1

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

AL-Tamimi
  • 672
  • 5
  • 9
  • If you don't specify actions in the URL, then how do you differentiate between actions? e.g. "add" vs "delete"? Relocating that to a POST parameter seems very unintuitive and potentially dangerous. – Cerin May 27 '15 at 19:13
  • your $_Server['REQUEST_METHOD'] will tell you what method you are using. you will map that request with an action in the backend. There are also other ways to achieve this. – AL-Tamimi May 27 '15 at 19:52
  • Please give this a good read. Also read the comments. It is very helpful. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven – AL-Tamimi May 27 '15 at 19:52
  • you could also use Route Manager I also found this. http://stackoverflow.com/questions/359047/php-detecting-request-type-get-post-put-or-delete – AL-Tamimi May 27 '15 at 19:56
0

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.

user1431072
  • 1,272
  • 2
  • 13
  • 32