[gcs-pcs-list] more comments (plain text)

[Eric Hellman]

(resent in plain text at request of list members)


Now that I've had a chance to digest the spec and start to plan an 
implementation, I see more issues that could make it difficult to 
write good code, mainly in the area labeled "error handling".

1. silly injunction against non-unAPI parameters

# requests with non-unAPI parameters or an invalid combination of 
unAPI parameters (e.g. "UNAPI?format=FORMAT") should return status 
code 400 Bad Request

- this prevents me from doing stuff like invoking a test mode in my 
unAPI server with an additional parameter. in OpenURL we set aside 
_parameters for this.
-makes future versions of unAPI incompatible

2.  modality of response to UNAPI?uri=URI requests.

channel modality is generally to be avoided in well designed 
protocols.  If I ask a question, it should be reasonable to get the 
answer back in a single language which should not depend on the 
answer. If I ask "what kind of soup do you have today" the answer 
should be "chicken noodle" or "sorry, no soup today". Using French 
only if there is no soup makes no sense.

When I build an client for an XML service, I delegate the message 
handling to an XML Processor (usually with XSLT doing most of the 
work). The processor will throw an exception if the response is not 
well formed xml; this is usually because a service is broken. If I 
have to listen for a 404 response just in case there are no available 
format for an item, or if the item is unknown, then I can't handle 
that inside the XML processor. As the spec is currently written, it 
is not clear whether anything is to be sent in the body of the 404 
response. It's not clear if client could rely on receiving a 
well-formed xml body message along with the 404 header .

  whatever the HTTP response codes are, I think that, to make it 
easier to develop robust clients, an unAPI  response to a 
UNAPI?uri=URI request should ALWAYS be well formed XML. When no 
metadata object is unavailable the body of the 404 response should be:
<formats>
<uri>info:sid/example.com/12345</uri>
</formats>

3. those response codes

As for the use of http response codes, the use of http code 300 looks 
bogus to me- shouldn't that be used for http content negotiation? If 
someone used an http client stack that supported http content 
negotiation, wouldn't this break? I admit it's bee a while since I 
looked at the http spec, but really if this is what is desired, then 
the unAPI spec needs to explain to the reader why these odd codes are 
used.

-- 

Eric Hellman, Director                            OCLC Openly 
Informatics Division
eric at openly.com                                    2 Broad St., Suite 208
tel 1-973-509-7800 fax 1-734-468-6216              Bloomfield, NJ 07003
http://www.openly.com/1cate/      1 Click Access To Everything