REST API - What to return when search criteria (queryParams) doesn't yield any results

Question

I am designing a REST API and throughout the API we have used HTTP Not found / 404 when an object/resource we are trying to access doesn't exist.

Ex: http://host/someobject/1

But the current one scenario is little different. I have the URI which searches the data with query parameters.

Ex: http://host/someObject/find?param1=param1value&param2=param2value

The query parameters are optional but at least one criteria must be provided for successful request. I am currently returning empty list when search result is empty assuming the URI exists but data not present at the moment.

Can any one shed some light on this scenario ? Should I return empty array with Status code 200 or something else ?

Answer 1

TL;DR - return the same thing you would return with N results, using N = 0.

http://host/someObject/find?param1=param1value&param2=param2value

Keep in mind that, from the point of view of REST/HTTP, the URI above is not a query; it's an identifier for an information resource. The part of the identifier (which is named Query by the RFC-3986) is just "non-hierarchical data".

The fact that your implementation parses the URI, and uses the tokens it finds as inputs to a query is an implementation detail, and is deliberately hidden from the client by the uniform interface. (Consider, for instance, the case where the client GET request passes through a cache between the client and the server; the cache might use the URI as a lookup in a key value store, and -- finding a representation there -- will send the result back to the client without forwarding the request to the server).

Ideally, your resources and their representations will be stable, even when your implementation may not be.

The query parameters are optional but at least one criteria must be provided for successful request. I am currently returning empty list when search result is empty assuming the URI exists but data not present at the moment.

Perfect.

I assume the comment of you says my implementation is fine ?

Yes.

Also i found some of the persons saying verb shouldn't be there and representation should be objects/?param=value or Objects?param=value.

A quick overview

REST doesn't care what spelling you use for the resource identifier Neither does the web -- as far as the other parts of the web are concerned, your URIs are opaque. Client code is not supposed to be interpreting the identifiers, or relying on their interpretation in any way. The only thing that is supposed to care is the origin server (which needs to route the identifier to the appropriate implementation).

The "rule" you are quoting is analogous to a coding style guide recommending best practices for variable names. The motivation for the rule is based on REST and the web; not by specification, but by deeper ideas.... Fielding's definition of resources:

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource.

REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components.

It follows that any resource that returns a representation must be a thing that has state. So naming guidelines encourage spellings that identify the resource as a noun, rather than a verb.

"Find me the objects that satisfy these constraints" is what your URI says, but that's not aligned with the concept of resources. The guidelines are encouraging you to instead think "Get me the current state of the collection of objects that satisfy the following constraint", and then to choose an identifier that is consistent with this resource.

I am pretty confused when I read these different blogs with different opinions

• That's not your fault
• You would still be confused if you were a native English speaker

Most programmers get by with studying a few things, then learning the rest by asking people nearby. Which means that a lot of the practical "knowledge" that people have comes from an oral tradition; the story changes each time a new person tells it, and it gets confused with other things.

In the case of REST, the distortion got to a point where the people who knew the original story started looking for a new name to use, just to be able to reintroduce the original ideas.

Answer 2

In my opinion both 200 with empty list and 204 No Content found is correct implementation.

200 successful means you were able to do operation successfully and you are returning the result. An empty list is a valid result set.

204 means the operation you tried successfully and server didn't return anything. So this also is valid.

the world of RESTful is so refined that at the end of it sometime it goes to your personal preference and my personal preference will be 200 with empty list.

Answer 3

As 404 means: 404 – Not found – There is no resource behind the URI I'd say, returning an empty list is valid, when URI and arguments are valid.

You could return a 204 with it: 204 No Content