users.list & and "fields" example about developer-docs

[Rodriq]

In https://developer.rocket.chat/api/rest-api/query-and-fields-info#fields-example , it's explained:

To only return the usernames for users, you would do something like this:
http://localhost:3000/api/v1/users.list?fields={ "username": 1 }

However, as discussed with @rodrigok, this example won't only return usernames, it would return the username field among other default fields, i.e. those listed at https://github.com/RocketChat/Rocket.Chat/blob/develop/app/api/server/lib/users.js#L53

Maybe the documentation is just out of date because this comment (back in 2017) looks to match with what explained in the current documentation.

So for me it boils down to the following questions:

• Do we still want to illustrate the same example, i.e "how to only return specific fields ? (my opinion is it's an useful use case).
• If we do, how do we do that ?
• Do we rather want to remove this use case, and explain how the default fields are coming into place (the specified fields in the request are merged with the defaults ones)

In addition, at https://developer.rocket.chat/api/rest-api/methods/users/list - where a ref to the Query and Fields Query Parameter page above is inserted - it is mentioned :

Gets all of the users in the system and their information (...)

all could let us think that what's returned by default (without fields parameter) are all the fields the callee has access to, while it's rather all fields the callee has access to among the default fields.

Also I would repeat there that including a specific field with 1 doesn't filter out the default fields from the answer, but rather merge it with some default fields.

Once we're clear with the points above, I'd be glad to propose a Pull Request.

@mhow2 You are right.

I've tested the endpoints and passed in the parameters like documented.
Setting a field value of 0, only excludes it from all the fields being returned. Meanwhile, some other fields(defaults) are being returned along.
Since there are just so many fields, not logical to go eliminating one after the other.

There's no clear way of returning just particular fields stated.