Add a /users REST API endpoint

[pjeanjean]

Alright, I posted a design page: https://design.xwiki.org/xwiki/bin/view/Proposal/RESTAPIendpointsforusers

Feel free to comment on it, in particular on the data model since this has not been discussed yet in this topic.

[vmassol]

@pjeanjean

GET /wikis/{wikiName}/users/{userWikiName}%3AXWiki.{userId} to get information on a specific user iff they are an actual user of wikiName (if the user does exist on userWikiName but is not a user of wikiName, we would return a 404) and the current user has read permissions on their profile.

As @tmortagne mentioned, we are trying to separate user APIs from implementation. Right now the only implementation for users are as wiki pages but we want to change that (hence the “user api” we introduced). Thus in all our APIs (including REST) we shouldn’t expose an internal representation of a user. Thus we should require the XWiki.<user id> format but just <user id>, so that it works when we store users in a place other than an xwiki page.

Thanks

[vmassol]

@pjeanjean

Alright, I posted a design page: https://design.xwiki.org/xwiki/bin/view/Proposal/RESTAPIendpointsforusers

Thx for that. I think you should explain a bit more what userId is for /wikis/{wikiName}/users/{userId}[?preferences={true,false}]. You could give an example, with something like: for a user located at XWiki.someUser, the userId value would be someUser.

[vmassol]

@pjeanjean

Alright, I posted a design page: https://design.xwiki.org/xwiki/bin/view/Proposal/RESTAPIendpointsforusers

Should we provide some “shortcut” REST endpoints for the main wiki or force the users to know that the main wiki is xwiki and use that?

Thx

[watery]

@vmassol

GET /users/current → current user (doesn’t matter which wiki since it’s the current logged in user, we can’t have a current user in a given wiki)

What happened to this one?

[pjeanjean]

@vmassol

I think you should explain a bit more what userId is for /wikis/{wikiName}/users/{userId}[?preferences={true,false}]. You could give an example, with something like: for a user located at XWiki.someUser, the userId value would be someUser.

I added a small part about that in the endpoint’s description.

@vmassol

Should we provide some “shortcut” REST endpoints for the main wiki or force the users to know that the main wiki is xwiki and use that?

I still wonder about that. I’m afraid it could be counter-intuitive for local users to see an endpoint they can’t authenticate to because it targets the main wiki without explicitly mentioning it. I also think for now it would be fine to first implement the more complete endpoints (since they will need to exist anyway) and then open discussions about potential shortcuts. I’m also not aware of other existing “shortcut” endpoint right now so I’m not sure if it’s something we want in general or simply have not discussed enough yet.

@watery

What happened to this one?

In the design page, it became GET /wikis/{wikiName}/user because, as @MichaelHamann mentioned, we would still need to specify the subwiki for local users if we want the request to be properly authenticated. Now we can still discuss whether or not we could shorten it to GET /user in the case we want to target the main wiki but that’s my point just above.

[watery]

@pjeanjean

In the design page, it became GET /wikis/{wikiName}/user because, […]

Ah, fine, I misread that then.

Thanks.

[pjeanjean]

I opened a PR: XWIKI-23915: Introduce a rest endpoint for user information by pjeanjean · Pull Request #5199 · xwiki/xwiki-platform · GitHub

[pjeanjean]

Hi everyone,

While working on this feature, we noticed during the PR review process that the semantics of the /wikis/{wiki}/users endpoint (responsible for listing users of a wiki) were not actually straightforward.
The initial idea was to emulate the behavior of the page Main.UserDirectory, but for subwikis it only lists global users that are either part of the local XWikiAllGroup or are the wiki’s creator. It’s not clear if this should be the expected behavior for this new API as well, or even if it this is still the expected behavior for the User Directory itself (where specific users could have every right on a wiki’s content without even be listed in it).

Since this would require more discussion, but the two other endpoints are done and are actually the main focus of the initial proposal, I would like to split this proposal in two and leave the user list as a future work. WDYT?

[tmortagne]

@pjeanjean

Since this would require more discussion, but the two other endpoints are done and are actually the main focus of the initial proposal, I would like to split this proposal in two and leave the user list as a future work. WDYT?

+1, the important thing is leave the endpoint /wikis/{wiki}/users available for this future implementation. Better actually discuss the details when we have a real use case for it.

I’m afraid that the way it was designed so far, it would have been pretty much impossible to use it in any real use case, which generally require at least some form of filtering.

[vmassol]

@pjeanjean

While working on this feature, we noticed during the PR review process that the semantics of the /wikis/{wiki}/users endpoint (responsible for listing users of a wiki) were not actually straightforward.

For me this means all users registered in that wiki, not all users who can access that wiki. Now it would be easy to add a query string parameter to also include users not registered in that wiki but who can access it.

@pjeanjean

Since this would require more discussion, but the two other endpoints are done and are actually the main focus of the initial proposal, I would like to split this proposal in two and leave the user list as a future work. WDYT?

Ok for me, but does it impact the initial need you had (which is, AFAIR, to be able to remove some code from the Cristal Extension for XWiki, by having the code in platform, and done in a generic way)? Ie does it mean we will still need to keep some code related to this in the Cristal Extension for now?

Thx

[pjeanjean]

@vmassol

Ok for me, but does it impact the initial need you had (which is, AFAIR, to be able to remove some code from the Cristal Extension for XWiki, by having the code in platform, and done in a generic way)? Ie does it mean we will still need to keep some code related to this in the Cristal Extension for now?

No, I did not need the list at all, it was only added during the discussions on the proposal to offer a more complete API on XWiki.

[vmassol]

@pjeanjean

No, I did not need the list at all, it was only added during the discussions on the proposal to offer a more complete API on XWiki.

ok so it makes even more sense to postpone it and create a jira issue for it + update the proposal for it on the forum. thx

[pjeanjean]

Proposal partially implemented (issue opened for the list users endpoint: Loading...) and part of XWiki 18.2.0: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/18.2.0/#HNewuserRESTendpoints