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:
know the watch status for a page / a space / a wiki
create or modify the watch status for a page / a space / a wiki, either to follow it, or to block it
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?
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
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/ 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.
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:
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.
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.
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 if we go for subresources then it’s pushing more towards having notifications/watch as you mentioned in your previous post no?
if we go for subresources then it’s pushing more towards having