CODEWITHSUNDEEP
resturluriurl-design
Deniz Ozger
Deniz Ozger

Reputation: 2613

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?

Upvotes: 3

Views: 751

Answers (3)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57249

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).

Upvotes: 1

Ray
Ray

Reputation: 41428

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

Upvotes: 3

sebmaldo
sebmaldo

Reputation: 59

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.

Upvotes: 0

Related Questions