Add a dedicated filter/query endpoint for single resources

[ro0NL]

We have a Product resource, REST based:

• /products
• /products/{id}

Products have EAN codes (unique field), we've added a endpoint for scanned EAN input:

/product?ean=input (note the singularity)

Ultimately, we may add additional validation filters, like:

/product?ean=input&flag=true

All query params are AND and respond 400 if we cannot find a single resource for it (one or null). Or in case of optional result, 200 or 204 could be considerable.

From a REST perspective, would it be nice to have this out of the box? itemOperation: { query: ~ } maybe? Given collections can already be filtered, i thought it's a small step relatively :)

Or maybe we can infer such an item operation from the collection operation (enable_single_query: true).

[dunglas]

I find this approach weird from a REST point of view. A resource must be identified by an URI, this URI should be unique. Here the same URI (/product) identifies several different resources. It looks like a violation of REST to me.

[ro0NL]

Hm, maybe you're right. However, in real-life APIs there's more than just "CRUD endpoints". We have several "do something" endpoints for process (we use the singular paths for these).

GET /product?ean=input (query a product)
POST /stocks/{id}/transfer (patch existing stock and create new stock)
POST /some-process

All valid API design IMHO :/

[soyuka]

GET /product/{ean} (query a product)

is even more restful. You should be able to implement that no? Why isn't the ean your product identifier?

[ro0NL]

@soyuka we use internal product IDs, for reasons :) the EAN is an external arfifact for us.

/product/{ean} would be confusing to me, as we have /products/{id} already. I cannot explain the different usecase between singular and plural then. Moreover, we need route parameter requirements then :( to avoid conflicts.

Whereas /product, i can explain to be a single query endpoint (as /products is the collection query endpoint)

[soyuka]

#2126 would be of interest maybe

Anyway, you should be able to do a custom operation that handles your custom case.