Question

I have an endpoint in an API I’m currently writing that is meant to return a filtered list of a user’s Facebook friends. Users authenticate to Facebook on the mobile app calling this endpoint, so the access_token is stored in the mobile app, not in the API’s database.

Endpoint: /users/:id/friends
Parameters: access_token (the requested user's Facebook access_token)
Return: A list of the user's Facebook friends who have the app installed

The action isn’t modifying any data; it is simply returning the filtered list. However, since an extra parameter (access_token) is required, it means that a GET request would not conform with the API’s routing structure, since no other GET routes have an extra parameter appended to them.

Which of the following HTTP requests is appropriate for this action?

GET /users/:id/friends/:access_token
GET /users/:id/friends?access_token=<token>
POST /users/:id/friends (passing 'access_token' as a POST param)

Answer 1

I definitely wouldn’t do it as a POST because you are requesting a resource, not modifying it. It may not fully conform with Rail’s RESTfulness, but I think it conforms a lot better than doing a POST to request a resource.

You can also do a GET on /users/:id/friends?access_token=<TOKEN> so that you conform more closely.