2

Given there is a one to many relationship between users and comments, and all ids are provided to be unique;

what are the considerations between naming the operation as:

DELETE /users/{user_uuid}/comments/{comment_uuid}

or

DELETE /comments/{comment_uuid}?

In the former user_uuid is redundant as it's not needed to delete a comment. Is it worth keeping user_uuid just to make the urls looks RESTful?

Deniz Ozger
  • 2,565
  • 23
  • 27
  • This question should be tagged with `uri-design` rather then `rest` as this has hardly anything to do with `REST` per se. Furthermore, this is rather opinionated. Concerning URI design: ask yourself, if you delete a user, should all of his posts be removed as well? If so, make the posts sub-resources of the user if not, keep them as top-level resoure. – Roman Vottner Apr 10 '17 at 18:01

3 Answers3

3

Both work fine for well structured RESTful resource--long as the comment_uuid is indeed a uuid. Neither hint at the underlying implementation or strikes me as screaming this is an RPC service :)

Whatever you choose, rule #1... Keep it consistent.

That being said, I prefer the first one as it reinforces semantic information that this is a user comment. I can see that and know pretty much what I'm getting back, without making a request.

Comment is a bad one to show a counter case, because most comments are from users, but think about this... conceivably, you could have some other type of entity that leaves comments, imagine registering bots in your system /bot/{bot_uuid},

Now if you go with just /comment you did you just delete a user or bot comment?

Compare this as you're scanning code vs /bot/{bot_uuid}/comment/{comment_uuid}. The more verbose is a lot clearer IMOP.

Finally, if someone provides a get request for a specific comment /users/{user_uuid}/comments/{comment_uuid} I know the URL for the user, just drop the omment part. Sure, most might guess, /user/{user_uuid}, but like I said, user and comment are bad examples, as you get more non-typical resource name it becomes less obvious. The thing is if you're alway's explicit, you don't have to worry when the resources looks like these:

  /widget/{widget_uuid}/contrawidget/{co_uuid}/parts/{part_uuid}
  /spaceframe/{spaceframe_uuid}/parts/{part_uuid}

Now would you just do parts:

  /parts/{part_uuid}

probably nots as it could be confusing to the consumer

Ray
  • 40,256
  • 21
  • 101
  • 138
  • Isn't a URI per se `REST valid`? – Roman Vottner Apr 10 '17 at 18:03
  • 1
    @RomanVottner Not every URI. If you use verbs in your resource names, even though it's technically valid in the spirit of REST, I don't think I'd consider that truly rest valid. Like: `/user/{user_id}/change_password` – Ray Apr 10 '17 at 18:05
  • verbs in URIs just give a RPC like smell to it though they don't violate any of the constraints given in the original paper nor [any of the rules](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) more clearly explained by Fielding in his often cited blog post – Roman Vottner Apr 10 '17 at 18:08
  • @RomanVottner Fair enough, verbs in URL's as valid/invalid is the wrong word. I'll update my answer to be clearer on this. This gets more into the technically (sure, any combination of legit characters in any order can technically define a perfectly RESTful resource) vs. practical good design choices. Kind of like someone equating the term `self-interested` to `selfish`--sure by definition, but they're not use interchangeably from a practical/colloquial sense. – Ray Apr 10 '17 at 18:24
  • well, technically uri-design has nothing to do with REST though everyone interprets the one for the other. REST is about decoupling clients from APIs, similar to browsers to certain web-content providers. REST achieves this decoupling by relying on certain constraints like statelessness, cacheability and adhering to backing protocols (HTTP). As content should be hypertext-driven, links found in responses can be used to retrieve further pages (states) and thus progress a given task. Anything other is not related to REST – Roman Vottner Apr 10 '17 at 18:34
  • Sure, technically hyper text transfer protocol has nothing to do with kitten pictures delivery, though everyone interprets it as it's primary inspiration. – Ray Apr 11 '17 at 13:21
1

Is it worth keeping user_uuid just to make the urls looks RESTful?

No. The business value that you get from making the identifiers look RESTful is indistinguishable from zero.

You might do it for other reasons: URI design is primarily about making things easier for humans. As far as the machines are concerned, all of the URI could just be UUIDS with no other hints.

That said, there is something important to consider....

/users/{user_uuid}/comments/{comment_uuid}
/comments/{comment_uuid}

These are different identifiers; therefore, as far as the clients are concerned, they are different resources. This means that, as far as clients are concerned, they are cached separately. Invalidating one does not invalidate the other.

(Of course, other clients, unaware that the DELETE happened, will continue using cached copies of both resources. Cache invalidation is one of the two hard problems).

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
0

I think that what your question is a design question and not a RESTful question as @ray said, and like for all design question the answer is... depends.

I prefer the first one also, because the comment (as I understand a comment) could not exist without a user.

But for this kind of questions I use the Entity-Control-Boundary Pattern (EBC) it basically propose a form to interact with your application in the context of certain entities, not using all the entities of the system, just the key ones, I generally use this as my rule to identify the paths that make more sense.

sebmaldo
  • 59
  • 7