I'm using swagger to prototype a RESTful API and I got to a situation where one property is part of a resource but not always should be filled.
Let's say my resource is stores
.
Basic endpoints would be:
GET: /stores
- returns a list of store
GET: /stores/{storeId}
- returns a single store
Say store is defined along the lines of:
Store {
id: integer,
name: string,
pictures: array[]
}
But when returning the list of stores, also returning every store's list of pictures is overkill. Pictures should be only returned for a single store request.
I'm confused on how to model that situation. On swagger, both methods responses are associated with a store
object.
Should I split store
into two objects and definitions so that each method return a different type even though only one property is different?
Should I use a query string parameter so that the consumer can choose whether or not pictures should be filled? Something along the lines of:
GET: /stores?fillPictures=false
or maybe
GET: /stores?detailed=false
When choosing the second option, the definition of a single store
would be the same no matter which endpoint is being accessed. That would mean an empty property would be transmitted to the consumer for every non detailed (with pictures) request. Should that be a concern?
Can someone shed some light on how to handle this scenario in a RESTful way? Maybe you know some API with a similar operation?
Thanks in advance.
pictures
array contain actual picture data or links where the pictures can be obtained when needed?