3

Consider a Web API with an endpoint api\LargeItem

A 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 api\SmallerVersionOfLargeItems\?

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.

5

This endpoint:

api\Items

Is not the same as this one:

api\Items\1

Therefore, they can return different responses. As you have indicated, getting items may just return a list with just a few properties while getting an item by ID may return a heavier object. Avoid decriptive terms such as "small" and "large" in your api/endpoints if the endpoints are named in that fashion.

Also, putting a version on the endpoint would be adviseable as well. Bottom line, the simpler the API is, the easier it will be for others to use.

  • +1 I'm not actually using the terms "Large" and "Small" I was just trying illustrate that they're different amounts of properties on the same object – Matthew Jun 15 '15 at 17:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.