CODEWITHSUNDEEP
restapi
omer
omer

Reputation: 1442

What's the RESTful way to return metadata on a collection of resources?

Say I have a REST API for accessing user notifications. I have an endpoint for getting all notifications:

GET https://server:443/api/notifications

Which returns the following response:

[
  {
    "status": "unread",
    "_id": "5db8228d710ab4b1e33f19b2",
    "title": "Some title",
    "time": "2019-10-29T11:29:17.402Z",
    "details": "Some details...",
    "user": "user1"
  },
  {
    "status": "unread",
    "_id": "5db8228d710ab4b1e33f19b3",
    "title": "Some title",
    "time": "2019-10-29T11:29:17.411Z",
    "details": "Some other details",
    "user": "user2"
  },
]

Now, I'd like to also be able to retrieve the amount of notifications for each user in a single request, for which the response will be something like:

[
  {
    "user": "user1",
    "count": 1
  },
  {
    "user": "user2",
    "count": 1
  },
]

What would be the best way, in terms of REST conventions, to do that?

Upvotes: 1

Views: 972

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57377

What would be the best way, in terms of REST conventions, to do that?

REST really doesn't answer that. REST tells you that you have resources, but it doesn't actually offer any opinion on where the "boundaries" of your resources should be.

Again, think "web pages". You could add your summary to the web page that describes notifications, and that would be fine. Or you could decide that the notifications are described on one web page, and the summary on a different web page, and that would be fine.

What REST does tell you is that caching is important; so if you think the cache controls for summary data should be different from notification data, then you want to be thinking about separating that data into a different resource. If you think the summary data and the notification data needs to be synchronized, then its more likely that they belong as part of the same resource.

Of course, there's nothing in REST that says you can't have multiple resources that return the "same" data.

If you wanted the summary to be part of the notifications resource, and also wanted that information to be independently identifiable, then you would use a fragment to describe the summary "sub-resource"; perhaps https://server:443/api/notifications#summary.

Upvotes: 2

Related Questions