This proposal is about adding information about the rights of the current user on the /pages endpoint.
When using the API to work with a page resource, it’s quite common to need to know whether, e.g., it’s possible to save a new version of the page, which would impact the UI in external applications relying on the API. But right now, when fetching a page we do not have access to this information easily, except by reading the required XObject to reconstruct the rights or by blindly attempting the request and see what breaks.
In Cristal, we rely on custom code (a XWiki extension) to check whether a page can be edited when we fetch it. Having this implemented would help us drop this code to align ourselves with the standard API.
As such, I propose the addition of a rights field to PageResource, that would simply contain booleans for the different rights the current user might have on a page: view, comment, edit, script, delete. Ideally, this would also be included in the responses of the /history endpoint, which would help, e.g., identifying private revisions.
I’m not fully sure what the expected value of the rights field is.
I can think of two options.
Option 1: an array
{
"rights": ["view", "edit"]
}
Option 2: a map
{
"rights": {
"view": true,
"edit": false
}
}
I tend to prefer option 1 as it is more compact.
Furthermore, I think we need to make the rights field optional and introduce a new query parameter that need to be set to true explicitly to see the rights returned (same as for the hierarchy for instance). I guess we can follow the same rule and introduce a rights query parameter with a boolean value.
At first sight, it looks a bit odd to me to get user metadata when asking about a page metadata.
Now, I understand the need and I think it could be ok (+0). I’m still wondering if that’s the right way to do it though, vs graphQL or other solutions. When displaying a page UI, you may need more information than just the page data, like the current user avatar, the current user display name, the panels on the side, etc. And thus using REST it would require some very specific endpoint to return all this data at once. GraphQL is supposed to solve this on paper. I’ve never used it and I hear that it’s not easy to use. Also maybe it’s not needed as much with HTTP/2+ since the HTTP connection remains open between requests. So maybe doing several requests is not such a performance issue.
Now if we add this information to the /pages endpoint, I think we need to:
Make it optional and off by default (see @mleduc 's proposal above)
Make it possible to pass the user’s id (or even user ids if we need to get the rights for several users)
Maybe make it possible to pass the list of rights to check (for ex, imagine that an extension is installed and contributes some rights and you need to get that info). Also, it would allow to return only 1 right if you need only that.
So in summary, I’m not 100% convinced but I don’t have a better solution except investigating/deciding if we want to go the GraphQL way or measuring if several requests is a real performance issue with HTTP/2 (I don’t even know if we’ve tried to use XWiki with HTTP/2 on Tomcat or other servlet containers and how it scales).
I don’t think this fits in the scope of this proposal (which only considers the currently authenticated user), but I also agree that the limit is muddy on what we consider important to display a page in a UI. A GraphQL endpoint could definitely mitigate this, but that’s also a completely different can of worms.
In the meantime, even if we later end up implementing a GraphQL endpoint, it’s not incompatible with updating the current REST API with information that is missing for integration purposes.
That’s a good point, I did not think it was possible to add rights but it’s also interesting to consider that even the 5 “default” page rights are rarely always needed together, so sending a list of rights to check might also be the best way to make this information optional.
The proposed design allows to selectively chose which rights to check, and in this context I think it makes more sense to use booleans in the response instead of the suggested shorter response (array of strings), but I’m open to discuss it further.
Right. I think that’s a good amount of +1, so I’ll just ask if the current design is more aligned with what @vmassol had in mind, and if @mleduc and @tmortagne still prefer the sublist solution if we go with the explicit list of rights to check during the request.
It’s unclear if having to know in advance the rights to request can be an issue, but I guess we can always improve later if that becomes an issue.
So fine with me.
As far as I can see, q=xxx&q=yyy&q=zzz is the standard way of sending a list of values as a query parameter. This is also what we do already with the search APIs to specify multiple scopes, for example.
If I may, this one would require to list all possible / existing rights, to tell which one is true and which one is false; I think the list is enough, another endpoint could provide all the rights, so one can evaluate those that are false