REST api design: How to manage multiple type of resources in URL?

Question

Lets say I have an Organization and Users inside that organization. To get a user in particular organization what should be the GET request url from below options?

1. /api/organization/:orgId/users/:userId
2. /api/users/:userId?organizationId=orgId

Any other suggestions are welcome.

• Click Upvote: I vote for the first. Much more readable.

Answer 1

Best to map onto what semantics you are trying to convey.

/api/organization/:orgId/users/:userId

This reads to me as there being a bunch of organizations, and for each organization, you have a bunch of users, and you want to get information for that user.

/api/users/:userId?organizationId=orgId

This reads to me as there being a bunch of users, and each user may belong to a bunch of organizations, and you are asking for the user's information in the context of that organization.

If it helps, here's the sort of situation where I'd use a query parameter:

/api/users/23642346?language=swahili

Since "language" just controls how the data is presented, not what it is, it makes sense to make it a parameter, not part of the data model.

Now I can't say for sure how to handle your data, as I don't know for sure what "Organization" actually is, but if it is a situation similar to what I described for the first option, that's the way I'd go.