1

So I'm currently working on building a restful API. Let's keep it simple and say I have two endpoints, both GET:

/products
/products/{productId}

The first returns a list of all products, the second returns a particular product.

The response for the first endpoint would likely look something this:

[
   {
       "id": 1,
       "name": ...
   },
   ...
]

However, when designing the second endpoint, I was curious whether it would be better to return a singular object like this:

{
    "id": 1,
    "name": ...
}

or a list of one object like:

[
   {
       "id": 1,
       "name": ...
   }
]

In my mind, the former feels more clean and natural (I am getting a particular product, the endpoint should return that product to me), but I could also see arguments for the latter giving more flexibility (ie. the ability to return an empty list vs. returning null).

Indeed, what is generally accepted as a best practice response when the id of the product does not match any stored products? In the first case it seems like you could return null or an exception (404 I would assume), but the second case you would also have the option of returning an empty list (similar to what would happen for the first endpoint if there were no products at all).

Is there guidelines on best practices here? I'm mostly ignoring the wrapper aspect (eg. wrapping the data in another json object and putting the data itself in a property), but if that's pertinent to this decision I'm fine with exploring it.

7

For endpoints denoting a single resource, such as /products/{productId} it's best to return this resource, not a list. If it does not exist, a 404 error is appropriate.

If you'd access the resource using a query parameter /products?id={productId} you've got a different situation. In this case a one-element or empty list would be the right result.

(Edit:) As @BryanBoettcher rightfully pointed out, this endpoint might return some enumerable structure that you can use to navigate through pages of results, so the actual JSON might look like

{
    "total":1,
    "first_index":0,
    "next_index":1,
    "items":[
        {...}
    ]
}

Note that some people might prefer a 404 error in that case, too, but IMHO the result "we have no product matching this query" is not an error and should be returned as just an empty list.

  • * shakes fist * – Bryan Boettcher Sep 8 '20 at 19:33
  • Could you elaborate on the differences of those requests ? My guess is the second request you showed could use different parameters, and those parameters might return multiple resources but I’m not sure. – Steve Chamaillard Sep 8 '20 at 22:13
  • 2
    @SteveChamaillard yes that's what I meant. For example, if you search for yellow products /products?color=yellow it is obvious that you can get a list of zero, one or many items. Handling the query parameter id differently in the same endpoint doesn't make sense. – Hans-Martin Mosner Sep 9 '20 at 4:51
4

You wouldn't return an empty list or null in a RESTful API -- you'd return a 404, which doesn't need a response body.

In a query or search (which /products is), I would expect to get a enumerable of some sort back. In a fetch (/products/{id}), I'd expect just the object itself.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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