resturluriurl-design

REST API naming convention: referencing unique resources with nested paths


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?


Solution

  • 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