How to manage public and private resource in a RESTful API

Question

I have a resource that has a public and a private response, and only some users in determinant situations can access the private response.

What would be the best implementation?

1. Two urls, one for the public and another for the private: resource/{id} and resource/{id}/private.
2. Same url, different response for each user: resource/{id}.
3. Same url with and a parameter that different the public and private: resource/{id}?private=true.
4. Other?

Answer 1

Your terminology is a little mixed up. You have one resource, and multiple representations. The resource should have one canonical location (URL). It's perfectly fine for different users to get different representations based on their auth level.

If you want a user to be able to request a specific representation of the resource, you have a couple of options. If you're using custom MIME types, the Accept header would be the best choice. A query parameter is your best bet if you're not using custom MIME types, but make sure it's something generic and consistent throughout the application. Don't just use ?private=true, but instead use something like ?representation=public. That allows you to add representations later and use the same parameter, and share the same query parameter with other resources that need to specify a representation. You should avoid using a separate URL.

Answer 2

IMO one resource should have only one URL. You can make use of auth-token in HTTP to check if the server should respond with a private response or a public response. Also if some user is requesting for some unauthorized resource, you can send a 4xx status.

Thus resource/{id} seems like a good choice.