[webservices] 204/404 vs empty xml doc

[Chad Trabant]

Hi Philip,

The rationalization goes like this: the FDSN services are all consistent, a properly formatted request that does not match any data will return a 204.  It is not possible to return an empty container for all data types, for example there is no empty miniSEED structure.  The DMC's services also return simple text responses for which there is no obvious "empty" container.  As for an empty response with nothing in the body (and a status code of 200), it is virtually identical to a 204, in fact they are logically the same for our purposes.

Clients should be checking the HTTP response codes for every request.  Detecting a 204 allows the client to short-circuit the processing of a response and avoid sending it to the parser.  In my opinion it is bad form to blindly send the response of a web service to a parser (XML or otherwise) without checking the HTTP response, otherwise you risk sending garbage (error messages, etc.) to the parser, and then there are security concerns.  Feeding an effectively empty document to a parser so it can tell you that it is empty is unnecessary and can be avoided by checking for 204.  There are some subtleties to this issue such as non-obvious behavior for web browsers, more on that below.

HTTP status codes are for status in general and not just errors, the whole 2xx class of codes are distinctly not errors.  As for our other services that return 404, yes they look like errors and yes they can be confused for many other types of errors (bad URL, down for maintenance, etc.), which is why we are moving away from 404 as a default.

There is some disagreement on when exactly to use 204s.  The efficiencies are not what we were really targeting, they are minimal for what we are doing.  The point is that sending an empty container is 1) not possible in all cases and 2) pointless when there is a code (that you should be checking) that is logically the same.

Regarding browsers, I assume you mean manually-driven web browsers like Firefox, Crome, etc.  The vast, vast majority of data requests to our services are not web browsers.  But there is a confusing interaction when you are using a browser with our services, in particular we see this with our "URL Builders".  So our services support a nodata parameter that can be set to 204 or 404.  By adding "nodata=404" to your request our FDSN services will return a 404 instead of a 204 in order to clearly show errors in a web browser.

Chad

On Apr 2, 2013, at 2:11 PM, Philip Crotwell <crotwell at seis.sc.edu> wrote:

> 
> Hi
> 
> Following up on my inability to catch a 204, can you explain the rationalization for using a 204 instead of returning an empty, but structurally correct, quakeml document for a query that doesn't match anything. For example is I ask for a time window and magnitude range that doesn't match any earthquake, send back this:
> 
> <q:quakeml xmlns:q="http://quakeml.org/xmlns/quakeml/1.2" xmlns="http://quakeml.org/xmlns/bed/1.2">
> <eventParameters publicID="smi:service.iris.edu/fdsnws/event/1/query">
> </eventParameters>
> </q:quakeml>
> 
> To be honest, I would rather have an empty XML document returned in the case where the query is well formed and valid, but just so happens that nothing in the database matched my query. HTTP error codes make it sound like there was an error, but that is not really the case here. There wasn't any data and so an empty xml document is a fine thing to return. 
> 
> I had a quick read of the http spec, and it doesn't really sound to me like a 204 is actually meant to mean, "sorry, no data", but rather is to be used in cases where there is some communications efficiencies to be had by avoiding a "entity body" and a update of the document view.
> 
> I guess I just don't see any advantage of 204 being the default for "no data" for these xml web services, especially when it will almost certainly cause confusion given the way browsers handle it, ie leaving the old page content on the display. 
> 
> $0.02
> Philip
> 
> 
> 
> _______________________________________________
> webservices mailing list
> webservices at iris.washington.edu
> http://www.iris.washington.edu/mailman/listinfo/webservices

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.iris.washington.edu/pipermail/webservices/attachments/20130402/81c5a1e6/attachment.htm>