OCS User/group API

[rullzer]

Eventually we need to expose groups and users via an API to allow clients (desktop/mobile/whatever) to have completion of sharing other than links.

I already proposed an PR for this in #13587. But recently I have been thinking we might want to go in a different direction than that PR. This issue is to discuss how we can properly expose this info.

What to expose

Basically we want to expose all the user group info that a user can access right now anyway. So a list of all groups and all users. Right now I see a use for the following info in the API

• user name
• full name
• avatar (either URL or also a fetch option)

Possible extensions (could also be added later)

• group membership
• e-mail

How to expose

Via a rest API interface. So for now that would mean

http://localhost/owncloud/ocs/v1.php/apps/files_sharing/api/v1/users

And then of course

http://localhost/owncloud/ocs/v1.php/apps/files_sharing/api/v1/users/<user>

And all the associated GET, POST, DELETE stuff (mostly GET at first I assume).

Exact API details are to be discussed but we for sure need something like:

http://localhost/owncloud/ocs/v1.php/apps/files_sharing/api/v1/users?shareable=1&search=<search>

This is for clients to obtain a list of users that he/she can share with and also search for a specific user (to facilitate auto complete). Of course the result should be paginated since they can be huge! Similar calls need to be available for groups

Why not use the provisioning API

The provisioning API was designed to solve a different issue. And thus most calls are not available for regular users.

Planning

It would be great to get this is rather sooner than later since this would allow awesome additions to clients. Also since we like to move the webclient to OCS calls this becomes a requirement for that as well.

However, I'd like to do this right and have proper testing. And preferably use the AppFramework.

1. First thing would be to agree on an API. I would propose to start with the bare minimum to make sharing work properly for all clients. Extensions can always be made later.
2. Write some code
3. Write tests
4. Goto 2 until done

We could use the tests from the current ajax endpoint as a basis.

Feedback

How does this sound?
CC: @DeepDiver1975 @karlitschek @LukasReschke @PVince81 @MorrisJobke and all the others I forgot.

[DeepDiver1975]

Sounds very reasonable - thx.

Regarding the size of the result set: we need pagination on this.
We might want to think about using link headers in the response (there is an rfc about this - github api uses this as well)

[rullzer]

@DeepDiver1975 you mean RFC#5988 I assume?

Probably would be something that we'd want to include in the AppFramework and then pass some parameters to the functions.

But I agree that this would be a good idea.

[MorrisJobke]

How does this sound?

@butonic talked some while ago about a more useful sharing behaviour. The idea was to not share to users, but to contacts. You don't want to have a autocomplete on all users of your instance. You most propably want to share to a contact (or email address). Then the receiver is actually the correct person and not yet another username you have to remind and type in correctly. Also the problem with exposing sensitive user data isn't a problem anymore. And searching through same names is also gone ;)

[rullzer]

@MorrisJobke interesting. However however I still see use for an API like this. Since you might want to search trough your contacts.

Further more you can't only share with contacts. Assume a big organisation you can't expect me to have contacts for every user I might ever want to share with. The same actually holds for e-mail addresses, since we currently do not enforce those as well. (Or multple e-mail addresses per user).

This API would not expose more than what already is exposed (at least not to start with). Currently the ajax endpoint also gives you all this info.

But I can see in the future this API being used to mark people as contact/friend/favourite

[rullzer]

So for a first setup we probably only need the GET request on the main url... so no users/<user> stuff is required yet. That stuff can always be added later.

So http://localhost/owncloud/ocs/v1.php/apps/files_sharing/api/v1/users

would have a signature like:

/**
 * @param string $search User to search for
 * @param bool $shareable Search only in users we can share with
 * @param int $limit Number of results to return
 * @param int $offset Where to start the results
 **/
getUsers($search = null, $shareable = false, $limit = 15, $offset = 0)

Which would then return an array with users containing:

1. User name
2. Display name
3. Link to avatar

Group would have a similar signature.

The difference here is that 2 calls are required by the clients, one to obtain users and one to obtain groups (currently they are grouped by the ajax endpoint). However I'm not sure that this is a big disadvantage as it should keep the code easier to read.

Also I'm not yet sure if this should be part of the files_sharing app or that it should be a separate app. If eventually we want to expand the app to allow users to update their own settings, mark users as friend etc. Then a separate app makes more sense.

[DeepDiver1975]

@DeepDiver1975 you mean RFC#5988 I assume?

yes - see https://developer.github.com/v3/#pagination

[DeepDiver1975]

@butonic talked some while ago about a more useful sharing behaviour. The idea was to not share to users, but to contacts.

yes - this is a pretty old idea which was basically implemented for some customer a while ago - while I like the idea I see no immediate benefit in terms of API. Furthermore I don't see any change in the sharing behavior any time soon.

[DeepDiver1975]

Also I'm not yet sure if this should be part of the files_sharing app or that it should be a separate app. If eventually we want to expand the app to allow users to update their own settings, mark users as friend etc. Then a separate app makes more sense.

I'd keep it with the sharing api - but as this is not files_sharing specific - it should be a core api from my POV.

[rullzer]

@DeepDiver1975 yeah it is part of sharing (at least the bare stuff) but this might be expanded in the future and I'd rather have it as a proper app then from the start. I agree that it should be a core app.

Any suggestions for names?

[DeepDiver1975]

I agree that it should be a core app.

not a core app but in core itself

[rullzer]

not a core app but in core itself

Ah yes that makes more sense ;)

[DeepDiver1975]

closing this in favor of #18117