dipole_moment dipole_moment - 25 days ago 9
reST (reStructuredText) Question

REST API filtering/search on a parent resource

Suppose I have a store such as Amazon that sells a variety of products such as computers and paintings. They are quite different from each other and have their own set of fields and logic.

In addition to the typical CRUD, I need to design a JSON API that allows me to:

A. Fetch an ungrouped list of paintings and computers. For example:

[computer, painting, painting, computer, ...]
ordered by date published (so with filtering capability).

B. Fetch only paintings

C. Fetch only computers

The RESTful approach will typically be something like:
/api/paintings
and
api/computers
which works really well for segregated results.

But my main concern is operation A - getting an ungrouped list of paintings and products sorted by date published. The way I see it, there are three approaches:

1) Create a new standalone resource called
products
such as
/api/products
which will have filtering capability and continue to use
/api/resource
for specific CRUD operations.

2) Create a parent
products
resource which will be used for filtering operations. So I can do something like
/products?order_by=published_date
And for more specific resources I can do something like
/products/paintings
or
/products/computers


3) Do not have a resource for paintings or computers. Instead have one for a generic
product
. I will then have most logic in the api layer and reduce the complexity of the client.

I am leaning towards approach #3 but wanted to get feedback prior to implementing since this will be a core feature of the API.

Tim Tim
Answer

I've always taken the approach the your API Layer should match your object modeling. So, the answer to your question would be it depends on the source data. Well, the source data after it's object modeling.

If you have an object model for Computer and for Printer, they should be resources like you've said. Do they share any data/functions? If so, you should have an object model for that, too, perhaps: Product. Then Computer and Printer extend the Product class.

With that in mind, design the API layer to mirror it. Since Computer and Printer both extend Product. Product as a parent of the Computer and Printer resources make sense.