[wp-trac] [WordPress Trac] #39544: REST API: Improve users endpoint in multisite

[WordPress Trac]

#39544: REST API: Improve users endpoint in multisite
----------------------------+-----------------------------
 Reporter:  flixos90        |       Owner:
     Type:  task (blessed)  |      Status:  new
 Priority:  normal          |   Milestone:  Future Release
Component:  REST API        |     Version:
 Severity:  normal          |  Resolution:
 Keywords:                  |     Focuses:  multisite
----------------------------+-----------------------------

Comment (by jnylen0):

 > We chatted through this a bit too and came to a conclusion that we can
 support a combo here.
 >
 > * `POST wp/v2/users` Adds an existing global user to a site.
 > * `POST wp/v2/users?global=true` creates a new global user and does not
 add them to the site.
 > * `POST wp/v2/users?global=true&add_to_site=true` creates a new global
 user and adds them to the site.

 This isn't making sense to me.  Here's what I think it should be instead:

 * `POST wp/v2/users` - creates a user and adds it to the site.  If on
 multisite, the user will necessarily be created globally, and this is
 fine.  The important thing is that the API client does not need to be
 multisite-aware.
 * `POST wp/v2/users?global=true` - creates a new global user and does not
 add them to the site.
 * `POST wp/v2/users?global=true&add_to_site=true` - we no longer need this
 new `add_to_site` parameter.

 IMO, the first case is not broken, even though it is partially a global
 operation and partially a site-specific operation.  This is how I expect
 the API to behave by default, even in a multisite context.  It's still
 pretty self-consistent this way:  we follow the rule that API clients
 don't need to be multisite-aware, and without the `global=true` parameter
 this newly created user doesn't appear on other sites of the same
 installation.  Also, we preserve backwards compatibility, and I think I'm
 not really OK with breaking something as basic as "POST to create a new
 user".

 From the [https://wordpress.slack.com/archives/C03BVB47S/p1493136608179107
 aforementioned Slack chat], there are three things we want to support:

 > a) creating a global user and adding them to the current site
 > b) creating a global user
 > c) adding an existing global user to the current site
 > The API can only do a), but it needs to be able to also do b) and c) I
 think (at least c) for sure).

 The more I think about it, the more I'm realizing that the thing is
 tripping us up is (c).  Everywhere else in the REST API, the following
 rule holds true:  "a POST to a resource without an ID is a CREATE
 operation".  Let's not break it here.

 So, it seems like trying to fit (c) into our existing endpoints is not
 going to be very RESTful no matter what we do.  Also, (c) is necessarily a
 multisite-aware operation, so we can assume that clients know exactly what
 they are doing here.  These two points suggest that (c) is a fundamentally
 different task than (a) and (b); also, that we have a good deal more
 freedom in how we approach it.

 IMO this will probably need to include either a separate API endpoint or a
 newly added feature of another API endpoint.

 I had a couple other ideas here that don't feel as fully-formed, but maybe
 they can lead to some good discussion at least.

 1. We could add a new endpoint like `/wp/v2/users/:id/sites`.  Here, a
 `POST` operation would make more sense: we're "creating" a "site
 membership resource" for this user.  This endpoint would also naturally
 support pagination, which would solve the problem of a user being a member
 of an extremely large number of sites.

 2. We could also allow `GET
 /wp/v2/users?global=true&email=something at example.com` to function as a
 search that returns limited data including a user ID (for users with the
 correct capabilities).  This would require two separate requests to
 perform the operation of adding a user by email address, but I think I'm
 probably OK with that trade-off, and there are other benefits to this
 approach (the client can fetch user data and confirm the intended result).

--
Ticket URL: <https://core.trac.wordpress.org/ticket/39544#comment:16>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform