REST API using GET Params

问题

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?

回答1:

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.

来源：https://stackoverflow.com/questions/26665301/rest-api-using-get-params

标签

rest

httprequest

getparameter