REST API for Notifications Watch pages

Hi everyone,

as part of my work on Notification watch buttons I need a new REST API for being able to follow / block a page / space / wiki.

So this API should allow to:

  1. know the watch status for a page / a space / a wiki
  2. create or modify the watch status for a page / a space / a wiki, either to follow it, or to block it
  3. remove the watch status for a page / a space / a wiki

IMO the REST API should be defined on the watch status element and so the 3 operations should use a GET for UC1, PUT for UC2 (I don’t really need a POST as I don’t need to send any body IMO), and DELETE for UC3.

The only issue I have is for UC2 to make a different between a block or a follow: I was thinking about only using a query parameter for that: I don’t think it would make sense to entirely provide a new REST endpoint just to make the difference as we’re handling same object and we’d need to repeat other APIs for GET/DELETE.

So first question is: do you agree on using that semantic?

Now the main problem for me is about defining URLs scheme for this REST API. First I want to reuse in the URL scheme what we already have for accessing page / space / wiki in other REST APIs, i.e.: /wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}.

But then I have two possibilities:

  • A. I use an action verb in the beginning of the URL, so the scheme would be something like /watchNotifications/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}
  • B. I use a noon at the end of the URL, so the scheme would be something like /wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/notificationsWatchStatus

Advantage of solution A is that it’s technically easier to write the API (I just need a root path and then I can define other operations for just a wiki, just a space, or a page) and maybe also easier to maintain it (we can add suffixes if needed).
Cons is that it doesn’t respect semantic of REST and it might be surprising to call watchNotifications for actually blocking notifications.

Advantage of solution B is that it’s more semantic. Cons is that it’s techically more difficult to implement: I need to define /wiki/{wikiName}/notificationsWatchStatus and then /wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/notificationsWatchStatus and then /wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/notificationsWatchStatus. I have to check but I’m not even sure I can do it in a single class. Or I’d have to compose a complex path with optional parts probably: in any case it’s more difficult to write.

As an API user I would maybe slightly prefer solution B, now as an XWiki committer and as the first contributor for this API I do prefer solution A. IMO here the only impact it might have, is that for other future REST API we should be consistent on the way of naming: right now I don’t have much example in mind, maybe we’d need a REST API for Likes for example? or ratings?


1 Like

as a user I’d +1 B

But I have verry little knowledge/insight in how difficult it is to program… I generally find that the short term easy win solution generally comes back to bite you in the butt long term when, as you write, other functionality is build on top of it… especially with REST i’d say standardisation is important.

But again, very little knowledge on xwiki so take my thoughts in that light :wink:

The generic format should be something like: /<resource name>/{id}/{sub resource}/{sub id}

So the question is: what is the resource for this REST endpoint. There are indeed 2 options:

  • A notification watch → option A → /notification/watch/wikis/.../spaces/.../page/... (for a document reference, we should be able to ask it for a space or a wiki too)
  • An entity reference → option B → /wikis/.../spaces/.../page/.../notification/watch

I think we should group all notifications REST APIs under the notification resource and have a watch sub-resource. I couldn’t find any REST endpoints defined in so I’m assuming we currently don’t have Notification REST endpoints. It’s important that the new REST endpoints we introduce can be extended to other notifications topics.

Is there any general proposal of REST endpoints for Notifications somewhere? I’ve seen this GSOC but didn’t find anything else in so far. It would be good to have such a proposal so that we have less risk of breaking something in the future for lack of a good generic design.

To go with option A, we’d need to check all other operations we can do on entities and check what REST endpoints we have defined already. EDIT: I’ve checked quickly and we have for example:

  • Translations: /wikis/{wikiName}/localization/translations[?locale=l&prefix=p[&key=k]*]
  • Icon Theme resources: /wikis/{wikiName}/iconThemes/icons[?[name=n]*]
  • Modifications: /wikis/{wikiName}/modifications[?start=offset&number=n&date=t]

So it seems to me that it would be consistent and logical to go with option B. +1 for that.


1 Like

Actually we do have a REST endpoints defined for notifications, sounds like it has never been documented though… Right now the endpoint allows to retrieve notifications. See: xwiki-platform/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-rest/src/main/java/org/xwiki/notifications/rest/ at xwiki-platform-15.10.8 · xwiki/xwiki-platform · GitHub

We actually use this API in XS for counting and displaying the notifications asynchronously.

To my knowledge we don’t, but I’m not sure what exactly we would put in it?

Yes that’s also what I’ve seen, but then there’s notifications which is the exception. Now /notifications currently doesn’t take any wiki / space / page parameter, so maybe we can consider it’s different.

1 Like

Do you think you could document it? In the notifications app page + maybe a link from the RSS page.

Idk, anything that can be done on notifications:

  • getting existing notifications for a user (we have it apparently with /notifications)
  • sending a notification to a user
  • marking notifications of a user as read
  • getting/modifying notification configuration for a user
  • etc

For all of these it seems we’re covered by the existing /notifications REST endpoint on which we could add sub-resources like /notifications/configuration or other (we already have /notifications/count).

Yes, it’s different for me and they’re orthogonal. So, all good with option B.

1 Like

Well since I’m planning to put the new resources in notifications-rest module I’m planning to create a page for that module. I will link it but maybe more in Notifications API extension page. In any case yes we need doc for it.

You make me hesitating :slight_smile: if we go for subresources then it’s pushing more towards having notifications/watch as you mentioned in your previous post no?

For me when it’s about entities, the resource = entity and thus option B.