RESTful route for a list of members that are not in a collection.

Question

Hey there,

I'm trying to figure out what the best way to show a list of members (users) that aren't a collection (group).

/users

is my route for listing all of the users in the account

/group/:id/members

is my route for listing all of the users in the group

/users?not_in_group=:id

is my current option for showing a list of users NOT in the group. Is there a more RESTFul way of displaying this?

/group/:id/non_members

seems sort of odd…

Answer 1

Spoke with my partner. He suggested:

/group/:id/available_members

Seems much more positive.

Answer 2

The main precept of REST is "hypertext as the engine of application state". The form of the URI is irrelevant, what matters is that it is navigable from the representation returned at the application's entry point.

Answer 3

Either query parameters or paths can be used to get at the representation you want. But I'd follow Pete's advice and make sure your API is hypertext-driven. Not doing so introduces coupling between client and server that REST was intended to prevent.

The best answer to your question might depend on your application. For example, if your system is small enough, it may suffice to only support a representation consisting of a list of users and their respective groups (the resource found at /users). Then let the client sort out what they want to do with the information. If your system has lots of groups and lots of users, each of which belongs to only a couple of groups, your available_users representation for any group is likely to be only slightly smaller than the entire list of users anyway.

Creative design of media types can go a long way to solving problems like this.