Include user rights in /pages REST endpoint

Development
,
1

Hi everyone,

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.

What do you think?

2

Thanks, +1 for the general idea.

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.

3

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

Thanks

4

+1

+1