# REST API for Notifications Watch pages

**URL:** <https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596>\
**Category:** Development\
**Tags:** proposal\
**Created:** [May 14, 2024, 8:37am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596 "2024-05-14T08:37:02Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![surli](https://forum.xwiki.org/user_avatar/forum.xwiki.org/surli/32/2687_2.png) [@surli](https://forum.xwiki.org/u/surli)\
**Post date:** [May 14, 2024, 8:37am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/1 "2024-05-14T08:37:02Z")

</div>

Hi everyone,

as part of my work on [Notification watch buttons](https://jira.xwiki.org/browse/XWIKI-19751) 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?

wdyt?

---

<div class="post-metadata">

**Author:** ![Wardenburg](https://forum.xwiki.org/user_avatar/forum.xwiki.org/wardenburg/32/4614_2.png) [@Wardenburg](https://forum.xwiki.org/u/Wardenburg)\
**Post date:** [May 14, 2024, 10:21am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/2 "2024-05-14T10:21:08Z")

</div>

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 😉

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [May 14, 2024, 12:13pm UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/3 "2024-05-14T12:13:34Z")

</div>

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 [https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/](https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/) 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 [https://dev.xwiki.org/xwiki/bin/view/GoogleSummerOfCode/AddaRESTAPItoXWikiNotifications](https://dev.xwiki.org/xwiki/bin/view/GoogleSummerOfCode/AddaRESTAPItoXWikiNotifications) but didn’t find anything else in [xwiki.org](http://xwiki.org) 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.

Thanks

---

<div class="post-metadata">

**Author:** ![surli](https://forum.xwiki.org/user_avatar/forum.xwiki.org/surli/32/2687_2.png) [@surli](https://forum.xwiki.org/u/surli)\
**Post date:** [May 15, 2024, 7:12am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/4 "2024-05-15T07:12:03Z")

</div>

> [@vmassol](#):
>
> 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 [https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/](https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/) 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.

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/NotificationsResource.java at xwiki-platform-15.10.8 · xwiki/xwiki-platform · GitHub](https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-15.10.8/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-rest/src/main/java/org/xwiki/notifications/rest/NotificationsResource.java)

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

> [@vmassol](#):
>
> Is there any general proposal of REST endpoints for Notifications somewhere? I’ve seen this GSOC [https://dev.xwiki.org/xwiki/bin/view/GoogleSummerOfCode/AddaRESTAPItoXWikiNotifications](https://dev.xwiki.org/xwiki/bin/view/GoogleSummerOfCode/AddaRESTAPItoXWikiNotifications) but didn’t find anything else in [xwiki.org](http://xwiki.org) 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 my knowledge we don’t, but I’m not sure what exactly we would put in it?

> [@vmassol](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [May 15, 2024, 8:23am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/5 "2024-05-15T08:23:43Z")

</div>

> [@surli](#):
>
> 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/NotificationsResource.java at xwiki-platform-15.10.8 · xwiki/xwiki-platform · GitHub](https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-15.10.8/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-rest/src/main/java/org/xwiki/notifications/rest/NotificationsResource.java)

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

> [@surli](#):
>
> To my knowledge we don’t, but I’m not sure what exactly we would put in it?

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`).

> [@surli](#):
>
> 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.

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

---

<div class="post-metadata">

**Author:** ![surli](https://forum.xwiki.org/user_avatar/forum.xwiki.org/surli/32/2687_2.png) [@surli](https://forum.xwiki.org/u/surli)\
**Post date:** [May 15, 2024, 8:27am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/6 "2024-05-15T08:27:49Z")

</div>

> [@vmassol](#):
>
> > [@surli](#):
> >
> > 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/NotificationsResource.java at xwiki-platform-15.10.8 · xwiki/xwiki-platform · GitHub](https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-15.10.8/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-rest/src/main/java/org/xwiki/notifications/rest/NotificationsResource.java)
> 
> Do you think you could document it? In the notifications app page + maybe a link from the RSS page.

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.

> [@vmassol](#):
>
> > [@surli](#):
> >
> > To my knowledge we don’t, but I’m not sure what exactly we would put in it?
> 
> 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`).

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

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [May 15, 2024, 8:33am UTC](https://forum.xwiki.org/t/rest-api-for-notifications-watch-pages/14596/7 "2024-05-15T08:33:11Z")

</div>

> [@surli](#):
>
> 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.
