Clarification on `users` API documentation.

[demitri]

On the page describing the arguments to list users API, the description under search is:

Limit results to those matching a string.

I'd like to request this be clarified: what field (or fields?) are being searched when a parameter is provided? Username? First name? Last name? More? Some combination?

[rmccue]

Internally, this uses WP_User_Query's search parameter. Per the docs for that:

When $search_columns is left empty, it tries to determine which column to search in based on search string.

The specific method for this is only in the source.

Agreed that we should clarify this in the docs.

[demitri]

Thanks for the clarification. I'm currently writing a new Python wrapper for the API, and I feel uncertain that there are (for lack of a better word) "hidden" parameters. I tried using search_columns and it worked, sort of. The search_columns=username case worked as expected, but

/wp/v2/users?search=4&search_columns=user_email

returned the user with id = 4, but this isn't what the URL specifies. Several variations on naming the columns have produced similar hit and miss results.

WP_User_Query seems like an implementation detail rather than the published spec. What should the guidance be here for someone writing against the API? Is what WP_User_Query takes part of the "official" API (e.g. is search_columns simply omitted?), or is the line not well defined yet?

I don't mean to be picky, but when one writes against an API, one like to be clear. :)