46

Lets say there's a Product with Orders. If you ask for /products/product_id, it will return a 404 if product_id doesn't exist. But should /products/product_id/orders return a 404 if no orders exist for this product or should it return an empty array?

Henke
  • 4,445
  • 3
  • 31
  • 44
dB.
  • 4,700
  • 2
  • 46
  • 51

4 Answers4

60

I would return an empty collection. A product with zero orders is a completely valid concept, so the existence of an empty orders collection makes more sense than a 404 which would infer that this product does not have a orders collection.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 2
    + 1, We went this way and I feel happy with the decision. – ale May 18 '11 at 14:57
  • 1
    Should orders be considered a resource in its own right? or a piece of information returned by the product_id resource? – chernevik May 18 '11 at 15:45
  • Chernevik Yes. If it's a different URL and it can return a 200 then it's a different resource. The server may handle both resources using the same controller, but they are two different resources. – Darrel Miller May 18 '11 at 17:26
  • 1
    Your future self will thank you for this when you decide you want to return metadata about the collection itself (like names, descriptions (your messages are self-descriptive, right?), versions, links, etc), regardless of whether or not there are any items in the collection. – fumanchu May 19 '11 at 20:31
  • 2
    Either in addition to, or instead of, returning an empty collection, you can also use the 204 status code ("No content") which is a little like 404 but since it's in the 200's, there is no implication that the user/client has made a mistake (i.e. mistyped a URL or something). – Tyler May 25 '11 at 23:43
  • 2
    @MatrixFrog The problem with return 204 is if a user does a search and it returns some values and then they do another search that returns no values, the user agent is not supposed to update the user interface following a 204. Therefore the user would think that they had received the same results again. – Darrel Miller May 26 '11 at 00:57
10

You really should do only one of two things

Either Return a 200 (OK) status code, and an empty array in the body.

Or Return a 204 (NO CONTENT) status code and NO response body.

To me, option 2 seems more technically correct and keeping in line with REST and HTTP principles.

However, option 1 seems more efficient for the client - because the client does not need extra logic to differentiate between two (success) status codes. Since it knows that it will always receive an array, it simply has to check for whether it got none, one, or many items and process it appropriately

Vihung
  • 12,947
  • 16
  • 64
  • 90
5

Do not return arrays. Return an object in any case, like

{ 
   offset: 30,
   limit: 10,       
   arr: []
}

it allows you to add metadata (for pagination or smth else)

usually with http status code: 200

Also, this is conventional web API behavior, driven by security concerns: https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html#always-return-json-with-an-object-on-the-outside

Ivan Rave
  • 1,759
  • 18
  • 15
1

In my opinion:

We're talking http status values here, and should be of a higher level of giving responses.

One should see this in layers of delegates. Like when your api is not able to answer a request, in case the api call itself is not available, then you could reply with a 404.

But when your call exists, and it could reply with a collection of data, but its an empty collection, you could return just a http 200, with an empty result.

I would use http status values to give an indication on the request validation, and not directly make it dependent on the content in the deeper api layers.

Or one could strictly follow protocols found on the net, but nobody follows them...

kaasdude
  • 1,336
  • 2
  • 8
  • 13