I worked with Ruby on Rails and RESTful api before and now with Django Rest framework. For this question let's say we only consider the case of JSON but not XML. It seems that when we expect an array as a result, if the result is 1 or above, we can happily get back an array with the proper content, but if the result is 0, we don't get back an empty array -- it actually will return a 404 HTTP status code with empty response content?

Is this always the case with RESTful resources, and is it true that if we don't define our API as REST or resource, then we can do whatever we want (and return an empty array)?

In a way, I think if it is math or functional programming, I would think that if a function returns a set or an array when the number of items is 1 or above, but give you back a null or raise an exception, instead of returning an empty set or empty array, I think it is a little strange behavior. And in the case of recursion, such behavior usually doesn't work, so I wonder if a behavior that is more "mathematically correct" may be a better behavior. But this question is about RESTful... whether its definition is that it should be 404 with empty response content but cannot be otherwise.

  • 1
    404 means 'page not found' the problem with the REST conventions is they are subjective rather than defined in the http spec
    – Ewan
    Mar 5, 2016 at 8:40
  • 2
    @Ewan It is not found, not page not found.
    – Eric Stein
    Mar 5, 2016 at 14:09
  • Thats the title, but its the page or 'resource' specifed in the URI which is not found.
    – Ewan
    Mar 5, 2016 at 17:54
  • Possible duplicate of Should "No Results" be an error in a RESTful response? Jun 22, 2021 at 6:55

2 Answers 2


You're right, the behavior is indeed strange. A null and an empty array are, semantically, two different things.

  • An empty array indicates exactly that: the array exists but contains no elements right now, given the query parameters.

  • An HTTP 404 indicates, on the other hand, that there is no array; for some reason, it makes no sense to have an array there.

Imagine a Flickr-type application with users, photos and comments. Imagine that only paid users can upload photos, but all users can comment. If the user 123 doesn't have a paid subscription and haven't posted any comments yet:

  • The query /user/123/comments would give an empty array, but:

  • The query /user/123/photos may result in HTTP 404 to indicate that the user is not expected to have any photos.

    Another possibility is to return an empty array, which is semantically correct. You'll lose the “this user doesn't have to have any photos” aspect, but it might not matter too much: if the client needs to know whether user 123 can have photos, the query similar to /account/123/status could be used to return values such as paid or free.

  • so you mean it is just up to the code providing the API to return an empty array or 404 to the api /user/123/comments? Would it be acceptable to return an empty array even for /user/123/photos or would it be considered semantically incorrect? Mar 5, 2016 at 13:43
  • I would expect anything returning a collection to also include metadata about that collection, in the form of links at least. Like @MainMa said, the difference is does the collection not exist, or does it exist but it's empty? If the user doesn't have a collection of photos (not registered), then they'd get a 404. If the user has an empty collection of photos (registered), they get 200 and an envelope containing an empty array, a link back to the user, a self link to the /photos uri, etc.
    – Eric Stein
    Mar 5, 2016 at 14:14
  • @太極者無極而生: I wouldn't consider an empty array to be semantically incorrect. I edited my answer to discuss this in more detail. Mar 5, 2016 at 20:45

Don't forget that 4xx errors are client errors, per HTTP specification. It really comes down to do you want to tell the client that its request was wrong, or do you want to say you don't have anything for that request.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.