Erndob Erndob - 1 month ago 9
reST (reStructuredText) Question

RESTful API design. When request comes with a filter should you return the values for that filter too?

Lets say client does GET request for /items/color/{color}

When server returns array of objects that have said color, should each item object have color property or not?

Client knows the color of returned items because he requested that color, so should server try to make a response size smaller or no?

EDIT: Can people touch more on saving bandwidth part? If it's better to return whole resource, can the answers include why it's better to return whole resource versus saving bandwidth, instead of just why whole resource should be returned.

Answer

In general (at least that's the idea of REST as I understand it), the result for the request should always be the complete resource. If the item contains a member color, there's no reason to suppress that member in the result. That would contradict the concept of resources of REST. A resource doesn't change its properties.

Suppressing members would not only come unexpected, it might even break the client when it actually expects that member.

Lets assume the client has functionality to parse the result of your REST call without a filter. All fields would be returned and the client would parse all the fields. Now the client requests the exact same resources (item), but suddenly the fields are different - the code from above to parse the result can not be reused.

Also, when you think about it, it's probably more work to suppress that member than to just return it.