RESTFul API endpoint design with filtering and authorization

Question

I am designing a REST API with consumers that have different permissions. I understand that a representation of a resource should not change according to user. Therefore I

Answer 1

In this case you can get away with just two endpoints (and one header!). Make sure the API for /documents is returning the Vary: Authorization header. Then you can use

GET /api/documents              // return all docs the logged-in user can see
GET /api/documents?userId=bob   // return all of bob's docs that the logged-in user can see
GET /api/documents/123          // return doc 123 if the logged-in user can see it    

It is not entirely unreasonable to nest the user a la GET /api/users/bob/documents. I find it to be harder for end users to learn APIs with a large number of endpoints, and I feel that the nested approach tends to create many endpoints. It's conceptually easier to go to /documents and see what you can filter on, rather than look at each endpoint and see what filters it has.