unAPI Version 1 (normative)

unAPI is a tiny HTTP API any web application may use to co-publish discretely identified objects in both HTML pages and disparate bare object formats. It consists of three parts: an identifier microformat, an HTML autodiscovery link, and three HTTP interface functions, two of which have a standardized response format.

An identifier microformat

(note: this has not been endorsed by the microformats.org project). To allow applications to identify objects on web pages, add an HTML ABBR block representing those objects that looks like this:

<abbr class="unapi-id" title="IDENTIFIER"></abbr>

Publishers may place anything, or nothing, inside the ABBR. For example, a reference to the book with ISBN 123456789X might be published with a human-readable string "ISBN 1-234-56789-X" inside the abbr:

<abbr class="unapi-id" title="urn:isbn:123456789X">ISBN 1-234-56789-X</abbr>

An autodiscovery link pointing to an unAPI service

To enable applications to discover unAPI service locations, each web page containing at least one unapi-id ABBR should contain an HTML LINK element having the following attribute values:

<link rel="unapi-server" type="application/xml" title="unAPI" href="http://example.com/unapi/" />

...where the value of the href attribute is a URL where unAPI requests are to be directed, without the trailing '?'.

HTTP interface functions

The three unAPI functions list formats available for discretely identified objects and provide direct access to those objects in those formats. The functions take zero, one, or two GET key/value parameters, respectively. The first two functions return an XML response entity; an informative schema for the response format is provided in the Notes below. In these function definitions, "UNAPI" stands for some unAPI service URL, "IDENTIFIER" is some object identifier, and "FORMAT" is some object format.

UNAPI (no parameters)

Provide a list of object formats which should be supported for all objects available through the unAPI service. Content-type must be "application/xml". An example response for a site that supports "oai_dc", and "jpeg" formats might be:

<?xml version="1.0" encoding="UTF-8"?>
<formats>
<format name="oai_dc" type="application/xml" docs="http://www.openarchives.org/OAI/2.0/oai_dc.xsd"/>
<format name="jpeg" type="image/jpeg" />
</formats>
        

UNAPI?id=IDENTIFIER

Provide a list of object formats available from the unAPI service for the object identified by IDENTIFIER. Content-type must be "application/xml". It is similar to the UNAPI response, adding only an "id" attribute on the root "formats" element; this echoes the requested identifier. An example response for a Pubmed citation available in text, Pubmed XML, and ASN.1 formats might be:

<?xml version="1.0" encoding="UTF-8"?>
<formats id="info:pmid/12345678">
<format name="text" type="text/plain" />
<format name="pubmed" type="application/xml" docs="http://www.nlm.nih.gov/bsd/licensee/elements_descriptions.html" />
<format name="asn1" type="text/plain" />
</formats>
    

UNAPI?id=IDENTIFIER&format=FORMAT

Provide the bare object specified by IDENTIFIER in the format specified by FORMAT. FORMAT should be a format name as specified by the value of the "name" attribute in the UNAPI?id=IDENTIFIER response, and the response content-type must be the content-type specified by the value of the "type" attribute in the UNAPI?id=IDENTIFIER response for this format. For example, to fetch the Pubmed citation from the example above in its Pubmed XML format, visit:

 UNAPI?id=info:pmid/12345678&format=pubmed 

Notes (informative)

Complete example

The unapi.info site news weblog at unapi.info/news co-publishes blog entries using unAPI via the WordPress unAPI plugin by Peter Binkley. Visit unapi.info/news/archives/9 and view source to see the unAPI autodiscovery link in the HTML HEAD:

<link rel="unapi-server" type="application/xml" title="unAPI"
    href="http://unapi.info/news/unapi.php" />
    

A unapi-id ABBR will be inside the blog entry DIV:

<abbr class="unapi-id"
    title="http://unapi.info/news/archives/9"></abbr>
    

Compose this information into a unAPI formats query for this weblog entry identifier by visiting http://unapi.info/news/unapi.php?id=http://unapi.info/news/archives/9. (Note: URIs intentionally not URL-encoded for readability). This should respond with something like:

<?xml version="1.0" encoding="UTF-8"?>
<formats id="http://unapi.info/news/archives/9">
<format name="oai_dc" type="application/xml"
    docs="http://www.openarchives.org/OAI/2.0/oai_dc.xsd"/> 
<format name="mods" type="application/xml" /> 
</formats>
    

Compose the unAPI base URL, weblog entry identifier, and the oai_dc FORMAT by visiting http://unapi.info/news/unapi.php?id=http://unapi.info/news/archives/9&format=oai_dc to see a Dublin Core record for the entry in the OAI-PMH schema for Dublin Core data.

Response format schema

This RELAX NG schema indicates which elements and attributes are required in unAPI format list responses.

 
    element formats {
	attribute id { text }?, 
        element format {
	    attribute name { text }, 
            attribute type { text }, 
            attribute docs { text }?,
	}*
    } 
        

Recommended HTTP status codes and error handling

unAPI defers to the response status codes already defined in HTTP [RFC 2616] to indicate the success or failure of an operation. In particular, it is recommended that unAPI implementors utilize the following:

  • 300 Multiple Choices for the UNAPI?id=IDENTIFIER function
  • 302 Found for responses to the UNAPI?id=IDENTIFIER&format=FORMAT function which redirect
  • 404 Not Found for requests for an identifier that is not available on the server
  • 406 Not Acceptable for requests for an identifier that is available on the server in a format that is not available for that identifier

This list is a guideline to encourage consistency across implementations. All HTTP status codes are relevant for any web resource; these status codes are particularly germane for unAPI.

Choosing identifiers

The unAPI specification does not require a particular type of identifier. It is preferable to use persistently maintained URIs (see RFC 3986) whenever possible; URLs, being network-resolvable URIs, are particularly easy for users. To encourage widespread use, however, URIs are not required.

Handling empty ABBRs

The unAPI identifier microformat allows for empty ABBRs. Note that some HTML checkers such as Tidy may strip out empty ABBRs, causing loss of the identifier information. Adding a comment or hard space in the ABBR should prevent this from happening.

Contributors

The following people contributed to the development of this specification:

  • Godmar Back
  • Peter Binkley
  • Eric Celeste
  • Daniel Chudnov
  • Kevin Clarke
  • Bruce D'Arcus
  • Leigh Dodds
  • Alf Eaton
  • Graham Fawcett
  • Jeremy Frumkin
  • Michael Giarlo
  • Eric Hellman
  • Xiaoming Liu
  • Phillip Pearson
  • Art Rhyno
  • Mike Rylander
  • Rob Sanderson
  • Ross Singer
  • Ed Summers
  • Steve Toub
  • Raymond Yee
  • Jeff Young

History

unAPI is an open specification developed in public on the gcs-pcs-list.

unAPI Version 1 was published on June 23, 2006.

unAPI revision 3 was published on May 18, 2006.

unAPI revision 2 was published on March 17, 2006.

unAPI revision 1 was published on February 16, 2006.

unAPI version 0 was published on January 14, 2006.