Empty list response codes

When you send a GET request for a resource using the Brightpearl API, your code should always be prepared to handle a 404 response as well as a 200. This is because we use 404 to indicate that your request returned 'nothing'.

This technique can be confusing and is not the only way 'pure' RESTful APIs manage 'no result' responses. The logic behind this as follows...

When you GET a resource by ID, it is generally accepted that a RESTful API should return 404. This is because REST tries to make use of HTTP's built-in status codes to avoid unnecessary parsing of response bodies (unlike, say, SOAP).

The Brightpearl API, of course, supports GET by resource ID but it also appears to support two other patterns of resource GET:

  1. Get a single, specified resource by ID - /warehouse/10 GET
  2. Get a number of specified resources using an ID Set - /warehouse/2-10,11,15 GET
  3. Get all of the resources of a particular type /warehouse GET

But actually these are just three instances of a single pattern - GET by ID Set where the ID Sets are a single ID in the first instance and the special 'empty' ID Set in the last.

We feel consistency is a valuable feature when using an API, so decided that if GET by ID Set returns 404 when the ID Set contains a single ID and no results were found, then you should get the same behaviour when the ID Set is empty or contains more than one ID. Note that since a 404 means that no results were returned regardless of how many you searched for, a 200 simply means that one or more results have been returned and NOT that every requested resource has been found. 

The most common alternative view is that a request that can potentially return multiple results should always return 200 and an 'empty list' structure. We don't do this because:

  • It seems a bit SOAP like - the body needs to be parsed just to find out your request returned nothing.
  • It makes GET by single ID a special case and generally special cases are a bad thing
  • We already have lots of API messages that support the ‘404 means empty list’ pattern - going back and changing these would break lots of existing code.
Have more questions? Submit a request