-1

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}
M20
  • 1,032
  • 2
  • 15
  • 34
Apps
  • 3,284
  • 8
  • 48
  • 75
  • Have you had a look at this: https://stackoverflow.com/questions/24059773/correct-way-to-pass-multiple-values-for-same-parameter-name-in-get-request – M20 Jul 27 '18 at 07:28
  • The question was different. It was more on to a better approach of using query params vs paths in the URL – Apps Jul 27 '18 at 10:42

2 Answers2

1

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
James
  • 80,725
  • 18
  • 167
  • 237
  • If I have to mention multiple types, like 'facebook','whatsapp','gmail' in one request then it would be difficult with this approach right? Will it be better if both are supported? like ?types=facebook,whatsapp and notifications/whatsapp , notifications/facebook. – Apps Jul 27 '18 at 10:40
  • 1
    @Apps so if it's expected that you pull multiple types, but not all types, then yes a query string parameter would be a better alternative... Personally though, I wouldn't have multiple ways of doing the same thing, consistency in an API is important in my opinion. Therefore, if the idea is you may select one or many types I'd suggest you go with `?filter=facebook,whatsapp` and for single selection `?filter=facebook` etc. – James Jul 27 '18 at 10:52
1

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

Non category dependent

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?category=whatsapp,facebook

category dependent

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:

/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:

/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:

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

Aurélien Bourdon
  • 186
  • 8