REST API URI pattern for different levels of resource details

Question

I have a resource "User" for which we store following details:

{ 
  "id": 123,
  "name": "John Doe",
  "address": {
    "line1": "411, ABC street"
    "city": "XYZ"
    "country": "ZZZ"
  }
}

I need three APIs to list my User resource:

1. API to return list of User Ids
2. API to return list of User with Ids and name.
3. API to return list of User with all information (i.e. id, name, address etc)

What URI pattern should I use for each of the above?

Answer 1

Since all three requests are for the same resource, all three should use the same URL. For example:

/users

If the client requests a different representation, it should use the proper HTTP header Accept. You should define vendor types that identify the different representations. For example:

To get the represenation including only the IDs:

GET /users
Accept: application/vnd.acme.users.ids+json

To get the represenation including IDs and names:

GET /users
Accept: application/vnd.acme.users.idsandnames+json

To get the represenation including everything:

GET /users
Accept: application/vnd.acme.users+json