Clash Royale CLAN TAG

REST API Designs with categories

Let's say there is a SINGLE mobile application which receives various types of notifications (like WhatsApp notifications, Facebook Messenger notifications ,etc). What would be a better REST API structure for this?

/users/test@abc.com/notifications //Gives all the notifications


There is a confusion between the below two formats on how .

/users/test@abc.com/notifications?category=whatsapp,facebook //Gives all the notifications


vs

/users/test@abc.com/notifications/whatsapp //Gives only whatsapp notification
/users/test@abc.com/notifications/facebook //Gives only facebook notification


To access an individual notification resource

/users/test@abc.com/notifications/facebook/{notification-id}


vs

/users/test@abc.com/notifications/{notification-id}


2 Answers
2

If a resource has a unique ID then it should be directly accessible from that, so in my opinion

/notifications/{id}


Would make most sense. In terms of filtering, this is probably more about preference than anything. Here's what I think would be the most idiomatic approach

/notifications // fetch all notifications
/notifications/facebook // fetch all Facebook messages
/notifications/whatsapp // fetch all WhatsApp messages
/users/{id}/notifications // fetch user notifications
/users/{id}/notifications/facebook // fetch user Facebook notifications
/users/{id}/notifications/whatsapp // fetch user WhatsApp messages


?filter=facebook,whatsapp

?filter=facebook

It really depends on how you define a notification resource and the relation with its category type (whatsapp, facebook...).

notification

category

whatsapp

facebook

Non category dependent

category

If the structure of a notification is not dependent on its category, then you want to access it without any category context:

/users/test@abc.com/notifications/{notification-id}


And you can use the category as a filter to a collection of notifications:

/users/test@abc.com/notifications/{notification-id}?category=whatsapp,facebook


category dependent

category

Otherwise, if a notification is structurally dependent on its category (e.g., if you want to define different actions when you deal with whatsapp notifications than when you deal with facebook notifications), then you might want to distinguish a notification according to its category:

whatsapp

facebook

/users/test@abc.com/notifications/whatsapp/{whatsapp-notification-id}
/users/test@abc.com/notifications/facebook/{facebook-notification-id}


In this case, you could have:

/users/test@abc.com/notifications/whatsapp/1
/users/test@abc.com/notifications/facebook/1


That define 2 different notifications (although it uses the same identifier).

Now requesting a collection of this kind of notifications is a bit different than the previous "non category dependent" case.

If you only want to have whatsapp notifications then simply call the category resource does the job:

whatsapp

/users/test@abc.com/notifications/whatsapp


But if you want to search on different categories, then you cannot apply your request to a specific category resource. Indeed, it makes no sense to ask for facebook notifications when you deal with whatsapp ones:

facebook

whatsapp

/users/test@abc.com/notifications/whatsapp?category=facebook # weird


One solution would be to make as many requests as there are categories requested:

/users/test@abc.com/notifications/whatsapp
/users/test@abc.com/notifications/facebook


But you will have to merge your results later.

Another solution would be to apply your query directly from

/users/test@abc.com/notifications?category=whatsapp,facebook


But the result will be different than the "non category dependent" case. Indeed, you won't be able to directly have your list of notifications, but a list of categories to access to your list of notifications.

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.