The documentation for rest/api/2/user/permission/search is confusing or wrong.

Here are the things that the documentation does wrong:

• It does not state that you must provide only one of issueKey or projectKey.
• It claims that the username filter can be empty but that does not currently work. This is probably a bug rather than a documentation issue: https://jira.atlassian.com/browse/JRA-43081
• The username field does not specify wether it works on usernames or userkeys. You should be able to provide keys instead of names.
• It gives no documentation on what to expect when an anonymous user hits the resource.
• It gives no documentation on what HTTP result codes to expect for a user that lacks the required permissions.

In short this resource is quite complicated and could use much more information around the permissions that are required, the fields that are required and what to expect in the error scenarios.