[OCS-API] get sharing recipients

[DeepDiver1975]

Followup on #16646

Mobile, desktop and web clients need to query the server for sharing recipients (Sharees).

This is the URL to be used:
http://localhost/owncloud/ocs/v1.php/apps/files_sharing/api/v1/sharees

Allowed method: GET

Query strings:

Key	type	description	default
search	string	the search string
itemType	string	the type which is shared (e.g. file or folder)
shareType[]	integer	any of the shareTypes (0,1, 4, 6)
page	integer	the page number to be returned	1
perPage	integer	the number of items per page	200

Result:
For each sharee there will be on entry in this form:

{
  "label": "admin",
  "value": {
    "shareType": 1,
    "shareWith": "admin"
  }
}

Label is the human readable display name.
shareType identifies the type (user, group, email, remote)
shareWith is the identifier to be use on the sharing api call

Pagination shall be supported as per https://developer.github.com/v3/#pagination

[rullzer]

If we want to add pagination we have to make sure we add proper header support to the OCS response stuff. Else it becomes impossible to unit test.

[rullzer]

Why do we need to itemtype?

[DeepDiver1975]

Why do we need to itemtype?

Sharing with remote users (federated sharing) is only allowed on files and folders

[rullzer]

Maybe it would be a good idea to (optinally) accept a list of share id's as well. That way the API can filter out already shared users/groups.

[rullzer]

Maybe it would be a good idea to (optinally) accept a list of share id's as well. That way the API can filter out already shared users/groups.

But we could keep the API simple and just leave it to the clients to filter this properly

[DeepDiver1975]

If we want to add pagination we have to make sure we add proper header support to the OCS response stuff. Else it becomes impossible to unit test.

#18118

[nickvergessen]

Adding a share ID is insufficient. There can be 0 to unlimited shares for the same item.
So this must take a list of share IDs at least.

[DeepDiver1975]

So this must take a list of share IDs at least.

let it be a list then

[nickvergessen]

I can't get this to work properly:

• Performant (not collecting all users from the backend)
• Pagination (allowing to paginate through pages)
• Easy2User (sending a list of users/groups that should be ignored, instead of doing that later in the client)

I can only get it to work with two of them. Since the client needs to collect the IDs anyway and most-likely displays the existing shares already, I'd say that's the easiest one to neglect?

[nickvergessen]

The result now looks as follows:

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message/>
 </meta>
 <data>
  <exact>
   <users>
    <element>
     <label>test</label>
     <value>
      <shareType>0</shareType>
      <shareWith>test</shareWith>
     </value>
    </element>
   </users>
   <groups>
    <element>
     <label>test</label>
     <value>
      <shareType>1</shareType>
      <shareWith>test</shareWith>
     </value>
    </element>
   </groups>
   <remotes/>
  </exact>
  <users>
   <element>
    <label>atest</label>
    <value>
     <shareType>0</shareType>
     <shareWith>atest</shareWith>
    </value>
   </element>
   <element>
    <label>btest</label>
    <value>
     <shareType>0</shareType>
     <shareWith>btest</shareWith>
    </value>
   </element>
  </users>
  <groups>
   <element>
    <label>test1</label>
    <value>
     <shareType>1</shareType>
     <shareWith>test1</shareWith>
    </value>
   </element>
  </groups>
  <remotes/>
 </data>
</ocs>

[rullzer]

Yeah filtering is not going to work in the current situation. Only if the user and group managers search function would allow passing a list of id's to filter out.

The reason to have to filtering was to limit the number of requests to the server. But I'm wondering how many shares of an item there are in practise on average.

[SergioBertolinSG]

any of the shareTypes (0,1, 4, 6)

According to documentation there is no 4 shareType but 3.
shareType - (int) 0 = user; 1 = group; 3 = public link; 6 = federated cloud share

[SergioBertolinSG]

@rullzer
I think making requests using shareType different than 0 (users) or 1 (groups) is useless, because it will be empty always isn't?

[rullzer]

@SergioBertolinSG nope. You can search for federated id in your address book. And we don't know what fancy types we might have in the future of course :)

[SergioBertolinSG]

@DeepDiver1975 @nickvergessen perPage parameter is called limit.
Changing name is ok?

[nickvergessen]

@SergioBertolinSG should be a bug, please create a new issue

[nickvergessen]

Reported here: #19007