0

Say we have the following server resource:

api.example.com/event/1

Which returns some arbitrary resource, say:

{
    id: 1,
    details: {
        type: 'webinar',
        ....
    },
    attendees: [
        {
            user_id: 1,
            first_name: 'Bob'
            ...
        },
        ...
    ]
}

It might be useful for a client to make a request to get just the event details of the event but not the list of attendees.

Is it better to provided two separate URLs for the resources and force two separate requests if a client wants both resources?

api.example.com/event/{event_id}
api.example.com/attendees/{event_id}

Or is it better to offer the same two endpoints, but optionally have the first one support a GET param to toggle the attendee listing on or off

api.example.com/event/{event_id}?listAttendees={true|false}
api.example.com/attendees/{event_id}

Where the listAttendees parameter will either have the representation return the attendee list or not.

Is it an common practice to allow GET params to change the representation returned from a specific URL?

moesef
  • 4,641
  • 16
  • 51
  • 68
  • Would a client ever want just a list of attendees without event details? – Centinul Oct 31 '14 at 00:18
  • I would go for Two distinct URS, as that completely in alignment with REST and you are asking for two different resources that can be identified by two distinct URIs. – Lyju I Edwinson Oct 31 '14 at 00:20
  • @Centinul you may want to cache the event details and attendees list differently. If for instance the event details won't change but the attendee list might. – moesef Oct 31 '14 at 18:27

1 Answers1

0

I'd say the most correct way to do that in REST would be with different media-types, or media-type parameters, but since most people don't use custom media-types, I often use something I call the zoom protocol. The idea is that you have a zoom or expand parameter, with a numeric value, and it recursively includes the children entities, decreasing the parameter until it reaches zero.

So, a request like:

GET api.example.com/event/1

Returns the plain representation for the event resource, without embedding anything. A request like:

GET api.example.com/event/1?zoom=1

Would include the immediate children of event, in your case, the atendees. Following on that:

GET api.example.com/event/1?zoom=2

Would include the immediate children of event, the immediate children of atendees.

To answer your question, in REST the whole URI is an atomic identifier, so the parameters are part of the URI. That can be a problem if you're using something that won't interpret URIs in the same way, like old cache servers who won't cache URIs with a querystring.

Pedro Werneck
  • 40,902
  • 7
  • 64
  • 85