Skip to content

Add a REST API endpoint for wporg users#184

Merged
coreymckrill merged 3 commits intotrunkfrom
try/user-endpoint
Mar 29, 2022
Merged

Add a REST API endpoint for wporg users#184
coreymckrill merged 3 commits intotrunkfrom
try/user-endpoint

Conversation

@coreymckrill
Copy link
Contributor

@coreymckrill coreymckrill commented Mar 11, 2022

This is a proof-of-concept for #182. It simply clones the Core users controller, but then strips out all the endpoints except the read access ones. The single user endpoint takes a slug instead of a numerical ID. The multiple users endpoint requires adding the slug query parameter and listing the specific user slugs you want to retrieve.

Additionally this controller limits the request context to either view or embed (omitting edit) so that only data fields that are already public are available in the response.

Another thing we could do here is add in some fields specifically from profiles.wordpress.org. Things that are viewable at a user's public profile page, like their bio, whether they are sponsored, maybe their badges?

To test

  1. Best to do this on a wporg sandbox.
  2. Upload the files and then while sandboxed, go to https://wordpress.org/wp-json/wporg/v1/users/{your wporg user slug} in your browser.
  3. Try adding the context parameter ?context=embed. That should show identical info to the default response. Changing embed to edit or anything else should give you an error message.
  4. Now try going to https://wordpress.org/wp-json/wporg/v1/users?slug={your wporg user slug}
  5. It should be the same as the first endpoint, except returns an array with one item.
  6. Try adding other user slugs, separated by commas.
  7. Compare the data shown to something like https://wordpress.org/wp-json/wp/v2/users. It should be all the same fields.
  8. Trying to retrieve user data via fields other than slug (e.g. id) shouldn't work.

@coreymckrill coreymckrill requested review from dd32 and ryelle March 11, 2022 23:55
@coreymckrill coreymckrill self-assigned this Mar 11, 2022
* Changes the single user endpoint to use a slug argument instead of
  a numeric ID argument.
* Adds a limited collection endpoint for retrieving multiple users at
  once, but you still have to specify their slugs.
@coreymckrill coreymckrill requested a review from iandunn March 24, 2022 18:55
Copy link
Contributor

@ryelle ryelle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changing embed to edit or anything else should give you an error message.

I tried view first, and view is allowed (that seems intentional though) — edit and other arbitrary strings do error. I noticed view (or no context) gives me an extra property on each user, meta. It's an empty array for the few users I tested. I assume it's because we don't have any registered meta on users.

Also tried querying on other properties with a slug, and it worked as expected— I couldn't include or exclude users, or query by anything but the slug. Order by name worked. I was able to restrict the fields with _fields=id,name, but couldn't add extra fields.

TIL there are users with the names "1" and "2". Otherwise trying to pass random IDs correctly errors 🙂

Overall, I like this as a first iteration - we might want to add onto it later, but it's set up so we can. 💯

@coreymckrill
Copy link
Contributor Author

TIL there are users with the names "1" and "2".

🤦

@iandunn
Copy link
Member

iandunn commented Mar 29, 2022

How valuable is it to extend WP_REST_Users_Controller? I'm wondering if some future changes there could have unexpected implications, since we're using it in a context it's not designed for.

If you want to err on the side of caution you could remove that and make this only return the specific fields that we currently have use cases for.

I haven't seen any tangible problems as a result of extending, though.

@coreymckrill
Copy link
Contributor Author

How valuable is it to extend WP_REST_Users_Controller? I'm wondering if some future changes there could have unexpected implications, since we're using it in a context it's not designed for.

Good question. The use cases we have for this endpoint right now (pattern directory, internal notes) expect responses to use the normal users endpoint schema, and have (some of) the same collection parameters. It would be simplest to ensure any future use cases also expect the same schema, so that if this endpoint ever gets supplanted by something in Core, everything would probably still work seamlessly. So, with that in mind, I think it makes sense to extend WP_REST_Users_Controller because it already defines the schema and collection parameters, and has some helper methods related to those.

@iandunn
Copy link
Member

iandunn commented Mar 29, 2022

Yeah, that probably outweighs the risks 👍🏻

Copy link
Member

@iandunn iandunn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't find any way to get private data 👍🏻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants