REST status code 204 on paginated result

Question

I am designing a REST like API for paginated data retrieval of a YUI-based client. The REST URL looks like this for a GET request:

/app/catalog/data?startIndex=<int>&results=<int>&sort=<sting>&dir=<string>

All parameters are optional, i.e. if no parameters are given, all data from DB will be dumped. Now say that there are only 1000 records in the database. Following reqeust is made:

/app/catalog/data?startIndex=1100&results=25

What status code should I return if the paginated result from the database remains empty though the request was fine?! I can't decide whether this is 204 or 404.

The produced media types are JSON and CSV.

Libertarian

Answer 1

I would say 204 is most appropriate. The request was successful, just with no results.

10.2.5 204 No Content

The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

Sounds exactly like the case.

Sistrunk

What would be the difference to a 404 in this case? An invalid sort column would be a Bad Request. – Libertarian

@Libertarian an invalid sort column would be a Bad Request because it is just an invalid option. However, in this case it is a perfectly valid request, it just happens to not have any return value. Furthermore, in the future, the request could return a value, while with an invalid sort column that will never be the case. – Sistrunk

So, I will stick with 204 which seems to be the best solution in this case. Thanks. – Libertarian

Answer 2

I can't decide whether this is 204 or 404.

Neither. Just return 200 with an empty result (empty XML document or JSON array, whatever you use). Typically I use REST services with paginated views so along with results page I return total number of records. This will help clients to realize the mistake. But technically it is nothing wrong.

Use 204 for DELETE operations (there's really no content to return) and for PUT.

BTW (bold mine):

if no parameters are given, all data from DB will be dumped

Believe, you don't want to do this...

Dali

As per RFC 204 is fine on GET. Why should I return 200 if I have just the perfect status code like 204? The amount of data is not huge, besides an output format can be CSV too in my case. – Libertarian

From httpbis, which is the IETF Working Group's work-in-progress to clear up some of the ambiguities in HTTP: "The 204 response allows a server to indicate that the action has been successfully applied to the target resource while implying that the user agent SHOULD NOT traverse away from its current "document view" (if any)." It's not intended to change the view to an empty set; it's intended to get work done without changing the view at all. See tools.ietf.org/html/… – Kiwi

Was about to say the same thing i.e. "Neither. Just return 200 with an empty result". That's the right thing to do. See https://mcmap.net/q/297944/-what-http-return-code-should-be-if-no-data-available for why 204 is not applicable per RFC 7231 Specs. 404 is definitely wrong as 404 is for resource not found (i.e. missing resource, not present but empty resource, which is what this case is) – Carrion

Answer 3

HTTP 204 in pagination response is not factible because of the payload. When paginating you should return pagination information like, items returned, total items, offset, etc. which makes no sense with HTTP 204.

HTTP 204 is useful on resource updates (ie PUT) when you want to explicitly say that the resource does not need to be fetched again (GET). For example, resources that have calculated fields and require a refresh of the view after every update, fetching those calculated fields from the server. Therefore, the 204 status code has specific use cases and must be designed and documented.

I would use one of:

• HTTP 200 with count=0 and no items in the returned list.
• HTTP 400 because invoker asked for an url that is invalid
• HTTP 404 because items to return are not found

Choose the one that best suits the way your API works. I think it's safe to return an error (4xx + error info) in this situation because the offset can be exceeded by one of these assumptions:

• A coding error
• Invoker is not fetching data from begining (no fresh state)
• Invoker ignored pagination data (present on each response)
• You are not using total field in the response (which is optional because there are some situations where you can not count all items or simply it's very expensive counting them). In this case, if your last page has the same number of items (count) as the number of items asked for in the request (limit), there is no way to know that this is the last page, so you try another one. In that last request you will get a count=0 in the response and you can stop asking for pages. This case makes it fair to return a 200 code also because the programmer did exactly what you asked for in the API documentation.

Cari

Answer 4

What format do you normally return your results in? I'd be inclined to make this 204 or even 200 returning an empty list.

Whatley

JSON payload with the results along with metadata for YUI. It may also return text/csv if requested to do so. – Libertarian

If the metadata can indicate to a human what happened (that the requested page/slice is empty), I'd definitely return 200 with empty data payload. – Whatley

No it can't. This is intended for M2M only. Humans should use the YUI-based interface. – Libertarian