This proposal is about adding an endpoint to the current REST API to access information about the existing users on a XWiki instance.
Right now, there is no easy way to externally get public user information, such as display name, email address and avatar (some of them can be obtained by accessing properties in XWikiUsers XObject instances, but display name for example still needs to be reconstructed manually). Having these would be useful to fix a few Cristal issues, namely:
If it could also expose technical details, such as displayHiddenDocuments, this could also be useful to update Cristal’s navigation tree accordingly.
As such, I suggest the following endpoints:
GET /wikis/{wikiName}/users/{userId}
GET /wikis/{wikiName}/users/current (to have direct access to the information of the connected user)
I’m still not sure on the format that should be returned by these, however. In XWiki, we have the class UserProperties that includes both basic and technical information, but it’s missing properties available in the XWikiUsers XObject such as public blog and company. Both these options also do not include the link to the current avatar.
+1 in general. Make sure to check if the REST user has view permissions on the user profile page.
Personally I’d prefer:
GET /users/{userId} → user userId in the main wiki
GET /users/{userId}/wikis/{wikiName} → user userId on wiki wikiName
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)
I also prefer the most specific path segment first (ie here we’re not asking about wikis but about users), but I don’t know what’s the best practice in REST.
I tend to agree, but we have the problem that authentication for subwiki users might not work unless you specify the subwiki, see XWIKI-17936. This seems painful, but I fear it means that we need the wiki in the path as suggested by @pjeanjean.
Also, it’s not clear to me what userId is in the path as we have no concept of user IDs as far as I know. The only string serialization of user references that I’m aware of are full document references.
It would IMO make a lot more sense to use the more standard /wikis/{wikiName}/users/{userId} as suggested by @pjeanjean for consistency, and proper authentication.
For the API, we have UserReferenceSerializer (specifically ConfiguredStringUserReferenceSerializer), but indeed the reference format depends on the storage config. So for me the reference needs to be in the storage format configured on the wiki being targeted.
I’m not entirely sure I agree with this. It makes sense to start with /wikis for requests about the model, i.e. anything related to entities. Even if currently the user is an entity, we want to get away from this (hence the new user api).
I reacted to your /users/{userId}/wikis/{wikiName} proposal, which does contain the wiki. To me, if you have the wiki, it should be put before (again because it’s a standard XWiki REST prefix and because it’s also used for authentication).
Maybe without the wiki part if we want the wiki part to be specified as a REST path segment, to be more generic (in case other storages don’t specify the wiki in the reference).
We might need a localDocumentStringUserReferenceSerializer impl for this though.
Or indeed we request a full path, idk.
(more thinking) Another option is, for the “document” store case, to only use the last part of the user name. AFAIR we have some resolver for it, so that would work. It seems nicer/cleaner and closer to what we would use with a different store. We would just need some verylocal component impl on the serialization part.
Actually it’s the opposite, the wiki part is part of the user id (its storage location in the case of a document based user). It might not make any sense for another kind of user. What’s in the path is only supposed to indicate from where you are accessing the user, not where the user is stored.
