Consider a Web API with an endpoint
LargeItem is a pretty big object with lots of properties and long strings.
A user can
GET any one like so
api\LargeItem\1 which returns the
LargeItem having Id 1
However we often need to populate lists of these items for user selection and when doing that we never need the big rich hydrated object.
On one hand the user can expect to just call
api\LargeItem and to retrieve all of them... but I never intend my user to consume the big collection of rich objects like that. When they want a list I'd rather give them
SmallerVersionOfLargeItem which maybe just has Id and Name, for example.
Is there a guideline or standard for whether it's ok to return differently shaped objects from the same names endpoint given different URL inclusions?
Is it preferred to have an endpoint like
EDIT This is equivalent to the
ShouldSerialize concept in JSON.Net except without using a
?fields property in the API call.
To clarify: My Api api doesn't use the terms "Large" and "Small" in reality. I'm just using them here to illustrate that these are just different fieldsets of the same object.