Let's say I have User resource which has Address sub-resource (let's forget about why this is a resource instead of attribute). To get a user's address, I can do GET /users/{id}/address

Now I want to have an API which returns all the addresses regardless of their owners. I can do GET /addresses. This feels a little bit hacky.

Another option is to move the Address resource to the top level.

  • GET /user-addresses to get all addresses
  • GET /user-addresses/{user-id} to get a specific user's address
  • POST /user-addresses/{user-id} to create an address

Which one do you prefer? Have you seen similar patterns before? Thanks!


If you want to return all of the user's addresses, then I would map that to /users/addresses.

Moving address outside of the users resource in the endpoint tells me I'm getting more than just user addresses (ie. Store address). I'm assuming that's not what you're going for.

And anything like user-adresses sitting beside the user endpoint looks very messy, I'd avoid that.

  • The /users/addresses looks like a user resource and the id is addresses. So the path more or less conflicts with the /users/{id}. – wanghq Dec 17 '18 at 6:17
  • I disagree, but if you're actually worried about that then go with /addresses or /users/*/address – Adam Bates Dec 17 '18 at 14:37

REST is a limited concept. It's a good mechanism to read and write individual data objects or small sets. There is no answer in REST itself on querying, paging, sorting, command execution or god beware asymmetry or CQRS. That doesn't mean it's not good, but the answers vary. Most APIs in fact have a need for querying, paging and sorting to handle larger amounts of data. One can look to json:api for one example for such semantics.

I would look at the paths where the client will locate addresses from a use case perspective. Need to find all users in a zip code? fine,


On the other hand,


doesn't sound right for me. We are not reading users with adresses in ZIP code 12345. We are reading addresses in ZIP code 12345.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.