I was reading this post on designing rest APIs on dev.to, when I remembered an interesting discussion I had had a while ago when working on a feature. Warning: This might be mostly rant.
The feature in discussion here allowed the publisher of an extension to reply to reviews left by users on the extensions product page. The publisher could only create and edit a reply, delete had to be done via a support email to our team, but rest APIs were available to delete a reply that required admin permissions. As you can notice, these nicely fall into crud operations. Now, the reviews feature had already been implemented, modeled using REST. How would you model or design the new reply feature in terms of REST?
Do you consider the reply as a separate resource, and model crud operations on the new resource? Do you expect someone to HTTP GETÂ a reply only? Does a reply make sense without the context of the review? Treat the reply like a sub-resource with its own crud operations?
Or are you the kind that thinks of replies as a property of reviews? A review either has a reply or not. Creating a reply would be like updating the review so you do it via a patch review call. Editing a reply is pretty much same so that too is done via patch. In this case the patch payload has instructions on what to do for the server. If the payload says update-reply, you either create or edit the reply. If the payload says delete-reply then you delete the reply associated with that review. But is this scheme ugly?
If you think of replies as a property, a call to get reviews for a product returns all the reviews and each review object has a reply object if one exists. Do you think getting replies should be optional and done based on a request Param? Something like get /extensions/my-awesome-extension/review
We went with the latter approach. What are your thoughts on this?