[gcs-pcs-list] usability of the unAPI specs, other comments

[Eric Hellman]

For reasons of having lots on my plate recently, I've not been 
following the discussion of unAPI in detail, and I have only today 
been able to study the spec. Here are my comments. Please forgive me 
if I have missed previous discussion, I hope my perspective properly 
simulates someone coming to the spec afresh, as those are the people 
you have to write for.


just a few notes on usability of the unAPI spec.

1. the unapi spec documents are undated- please annotate them with 
the date they were published
2. each spec should link back to the previous version of the spec
3. http://www.code4lib.org/specs/unapi/ should list all version of 
the spec somehow. http://www.code4lib.org/specs/unapi/current should 
alias to current version.
4. there is no author or contact information in the dpec document - 
if the gcs-pcs list is to be considered the author, then it should 
say that; anonymous shouldn't use the royal we.
5. In the interests of being accessible to the "rest of the world", 
the name needs to be explained or at least meaning disclaimed. 
"Universal API?"
6. "microformat" is not explained. there should be a link.
7. please add html name anchors so that links to spec can reference fragments
8. please replace curly quotes in quoted code with straight quotes.


comments on the technical content

A URI microformat
1. as in COinS spec, should warn against empty spans
2. considering functional overlap, should probably reference COinS as 
an alternative for richer metadata embedding; COinS spec would return 
the favor citiing unAPI as a "lighter weight" embedding method.
3. info uri is not a "rest of the world" thing yet; should add an 
explanatory link
4. The uninitiated will want to know why not :
     <span class="unapi-pmid" title="12345678">PMID 12345678</span>
5. If I may be forgiven for commenting after the subject is tabled, 
using a real URI as current has the advantage of retaining 
compatibility with OpenURL, which I think is a good thing. There is 
nothing to be won (in terms of compliance with a potential OpenURL 
Profile for unAPI transport) by changing the class name or adding a 
version identifier. It can compatible as is, with no changes. not 
using a real URI would break this, however.

An autodiscovery link pointing to an appropriate unAPI service
1. I continue to be worried about web pages that want to use more 
than one metadata server. For example, how about allowing
     <link rel="meta" type="application/xml" title="unAPI" 
href="http://example.com/unapi/" />
     <link rel="meta" type="application/xml" title="unAPI-isbn" 
href="http://isbn.example.org/unapi" />

and in the body:
     <span class="unapi-uri" title="12345678">PMID 12345678</span>
     <span class="unapi-uri-isbn" title="123456789x">ISBN 123456789X</span>

this would make it easier for metadata providers to specialize and 
potentially lift one barrier to implementation and propagation.

HTTP interface functions

1. I am confused about the function of
<name>oai_dc</name>
are these  random tokens, are they a controlled vocabulary? If these 
are meant to be machine readable, then a list or registry of standard 
name tokens is desirable. From farther down, I understand that these 
are really meant to be format-handles. if so, then only mimetype is 
guaranteed as informing usage. I guess this is ok. It would help 
readability if this functionality were disclosed immediately when 
introduced.
2. I trust there will be a real schema
3. when a metadata server sends back xml document which uses more 
than one schema,  it be possible to report multiple schemas in one 
formats? Or is it to be forbidden to send back this sort of metadata?
4. "URIs in unAPI HTTP calls must be url-encoded". This is ambiguous. 
What sort of URIs are not url encoded? I presume you mean they must 
be doubly encoded.
5. Why does the spec say to redirect to the object instead of simply 
returning the object? Why does it matter?
6. Why should the UNAPI ?uri=URI function should return status code 
300 Multiple Choices if there are 0 or one choices.
7. is zero metadata choices the same as object not found?
8. suppose a metadata server is set up to serve privileged users with 
privileged formats; I assume the usual http status codes would apply.

Bottom line; based on my reading the current spec we would probably 
want to add unAPI client capability to OpenURL referrer; this would 
certainly help to drive OpenURL 1.0 link-server adoption, which of 
course is what we care about.
-- 

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