resthttp-status-code-404http-status-codeshttp-status-code-200

Should I return a 404 error on a resource resulting in empty set?


If I have a resource with the following endpoint that lists all items within that resource:

/api/v1/resources

This results in:

[
  {
    "id": 1,
    "value": -100
  },
  {
    "id": 2,
    "value": -999
  }
]

It has various filters, for example:

/api/v1/resources?values_gte=999

If the filters exclude every resource and results in an empty set:

[]

Should I return a 404 status code, or a 200 status code?


Solution

  • Should I return a 404 status code, or a 200 status code?

    200

    You asked for the current representation of the resource identified by "/api/v1/resources?values_gte=999" so here it is: an empty JSON array

    Notice that this is exactly what you would do if somebody requested /foo.json, and that file on your disk happened to contain exactly the contents []

    HTTP status codes are metadata identifying the semantics of the response; they are used to distinguish representations of documents (2xx Successful) from representations of errors (4xx Client Error).

    The payload of a 404 response would be "a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.", not an empty document.