Q: unapi identifiers/formats
Godmar Back
I've been reading http://unapi.info/specs/ and I have a quick question
about unapi.
When you say "UNAPI?id=IDENTIFIER&format=FORMAT"
what are the namespaces for IDENTIFIER and FORMAT? My guess, from
spending 2 minutes reading the specification, is that it is outside of
its scope - but I may be wrong.
Even if it is outside the scope, is there a list somewhere with what
commonly used or agreed upon IDENTIFIERs/FORMATs are?
Thanks!
- Godmar
Richard Karnesky
>
> what are the namespaces for IDENTIFIER and FORMAT? My guess, from
> spending 2 minutes reading the specification, is that it is outside of
> its scope - but I may be wrong.
> Even if it is outside the scope, is there a list somewhere with what
> commonly used or agreed upon IDENTIFIERs/FORMATs are?
IDENTIFIERs are typically URIs, but different apps present them
differently (some even let the server administrator define the
formatting--others just use a URL/DOI/PMID/whatever.
Some formats in use are listed at:
<http://unapi.stikipad.com/unapi/show/existing+formats>
But it isn't comprehensive. Zotero can scrape MODS, MARC, Endnote,
RIS, BibTeX, and RDF formats from unAPI. MODS seems to be fairly
common, although most webapps seem to support a few of the others too.
UnAPI does provide a means of polling a particular server to see which
formats are supported.
--Rick
Godmar Back
Two follow-up questions:
Are clients supposed to go by "docs" attribute in format to determine
what a particular format name means?
For instance, if one server said:
<format name="marcxml" type="application/xml"
docs="http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"/>
and another said:
<format name="xmlmarc" type="application/xml"
docs="http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"/>
would a client be expected to recognize that both really return MARC/XML?
In other words, is format['name'] really just a local alias for
format['docs'] or does format['name'] have an pre-agreed upon meaning
between client and server?
What do I return if the id is ill-formed (as opposed to referring to
an identifier that is not found?) For instance, urn:isbn:345 where
'345' is not a valid ISBN. Or, "urn:bisn:" instead of "urn:isbn:"?
- Godmar
Richard Karnesky
> what a particular format name means?
something "special" for different formats. I believe it ignores them
& just uses the name.
Indeed, it seems that "docs" is currently used to help humans. In
some cases, "docs" isn't a machine readable schema.
However, there's no reason for clients not to try to intelligently use
the docs url as well (for things like version info and/or to identify
an apparently identical format hiding in a different name (as you
proposed)).
> What do I return if the id is ill-formed (as opposed to referring to
> an identifier that is not found?) For instance, urn:isbn:345 where
> '345' is not a valid ISBN. Or, "urn:bisn:" instead of "urn:isbn:"?
UnAPI uses HTTP status codes. Returning a 404 for any identifier not
on the server seems reasonable.
--Rick
Hammond, Tony
> > What do I return if the id is ill-formed (as opposed to
> referring to
> > an identifier that is not found?) For instance, urn:isbn:345 where
> > '345' is not a valid ISBN. Or, "urn:bisn:" instead of "urn:isbn:"?
> UnAPI uses HTTP status codes. Returning a 404 for any
> identifier not on the server seems reasonable.
Not really. Better would be to return 400 - Bad request.
The two examples are not valid URIs per the URN "isbn" Namespace ID
("urn:isbn:345") or the URN registry ("urn:bisn"). This is different to
supplying legal URIs in the request.
Tony
********************************************************************************
DISCLAIMER: This e-mail is confidential and should not be used by anyone who is
not the original intended recipient. If you have received this e-mail in error
please inform the sender and delete it from your mailbox or any other storage
mechanism. Neither Macmillan Publishers Limited nor any of its agents accept
liability for any statements made which are clearly the sender's own and not
expressly made on behalf of Macmillan Publishers Limited or one of its agents.
Please note that neither Macmillan Publishers Limited nor any of its agents
accept any responsibility for viruses that may be contained in this e-mail or
its attachments and it is your responsibility to scan the e-mail and
attachments (if any). No contracts may be concluded on behalf of Macmillan
Publishers Limited or its agents by means of e-mail communication. Macmillan
Publishers Limited Registered in England and Wales with registered number 785998
Registered Office Brunel Road, Houndmills, Basingstoke RG21 6XS
********************************************************************************
Alf Eaton
On 09 May 2007, at 04:39, Godmar Back wrote:
>
> Thanks for your answer!
>
> Two follow-up questions:
>
> Are clients supposed to go by "docs" attribute in format to determine
> what a particular format name means?
The 'name', 'type' and 'docs' format are all very informal, so a
machine couldn't definitively use them to tell what the response
format actually is. It can take a good guess though.
>
> For instance, if one server said:
> <format name="marcxml" type="application/xml"
> docs="http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"/>
> and another said:
> <format name="xmlmarc" type="application/xml"
> docs="http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"/>
>
> would a client be expected to recognize that both really return
> MARC/XML?
> In other words, is format['name'] really just a local alias for
> format['docs'] or does format['name'] have an pre-agreed upon meaning
> between client and server?
>
> What do I return if the id is ill-formed (as opposed to referring to
> an identifier that is not found?) For instance, urn:isbn:345 where
> '345' is not a valid ISBN. Or, "urn:bisn:" instead of "urn:isbn:"?
The identifier is just a string that means something to that
particular unAPI server, so doesn't have to be a valid anything. I'd
agree that a 404 Not Found response would make sense.
alf.
Michael J. Giarlo
The identifier is just a string that means something to that
particular unAPI server, so doesn't have to be a valid anything. I'd
agree that a 404 Not Found response would make sense.
+1
-Mike
Daniel Chudnov
The spec intentionally says nothing about what an identifier is. See the
informative note "Choosing identifiers". Also, the informative notes
recommend 404 Not Found for requests for an identifier that is not
available on the server.
As for voting on such things, I'm guessing that Mike was just indicating
his agreement using a voting-like convention... but just in case anybody
was wondering, version one of the spec is done, and will not be changed.
-Dan
Michael J. Giarlo
As for voting on such things, I'm guessing that Mike was just indicating
his agreement using a voting-like convention...
+1
:)
-Mike, abusing conventions since 1973
Godmar Back
choice of identifiers or format, people still have preferences
regarding them, as well as error codes.
The reason I'm asking all these questions is because I'm looking for a
sensible API to access libxess (libxess.sourceforge.net), a set of
tools to access legacy ILS such as III Millennium or others. For now,
I slapped on a unapi interface, see
http://libx.org/libxess/examples.html.
libxess currently supports retrieval by ISBN, proprietary bibrecord
identifier, and by title (pretending, for a moment, that a title would
be a way to uniquely identify an item.) For ISBN, urn:isbn: would be a
straightforward choice in keeping with RFC 3986 (*) and it is so
implemented.
Are there straightforward choices for the other two (bibrecord numbers & title?)
- Godmar
(*) BTW, could you hyperlink the RFC on the unapi.info/specs page?
Ed Summers
> his agreement using a voting-like convention... but just in case anybody
> was wondering, version one of the spec is done, and will not be changed.
Does that mean there will be no version > 1?
//Ed
Daniel Chudnov
It just means that version one of the spec is done, and will not be
changed. Has been so for a year.
Imho any talk of future revisions is jumping the gun, considering how few
uses we've seen so far.