UnAPI is set to become a very useful addition to the web toolkit of sites that purvey metadata, such as library catalogues. Within its domain, it renders the human-readable web machine-readable at a fine level of granularity. It does this by providing a simple mechanism by which a client application can fetch a full metadata record for the item being viewed. All that is needed is a couple of lines of HTML in the source page (which are invisible to non-unAPI applications and to human readers), and a back-end service that can provide the metadata on demand.

The unAPI server can easily be layered on top of an existing service such as an OAI-PMH server or an SRU server. This project provides an SRU-to-unAPI service. If you have a catalogue with a Z39.50 server, it is easy to provide an SRU service using IndexData’s YAZ Proxy. And if your Z39.50 server can search by record id, it is easy to use that SRU service to provide unAPI service. This project shows how to do this using Apache Cocoon as the unAPI server, but it could just as easily be done with other XML-aware web scripting environments.

This service is currently running experimentally in the University of Alberta catalogue. It can be seen in action by pointing a unAPI client at any full-record page.

Installation

  1. Install YAZ Proxy.

  2. Configure YAZ Proxy to allow searching by record id, using the rec.id field. This may require opening use attribute 12. Make sure that pqf.properties contains the line:

    index.rec.id = 1=12

    And in the configuration file for your server make sure that use attribute 12 is available by adding it to the default attribute list:

    <attribute type="1" value="1-11,13-1010,1013-1023,1025-1030"/>

    (Change the first part to 1-1010). Test it to be sure you can retrieve records using the record id.

  3. Install Apache Cocoon.

  4. Unzip unAPI-SRU.zip and add it to Cocoon’s mount table with a line something like this:

    <mount src="/Docume~1/Peter/MyDocu~1/projects/unAPI-SRU/" uri-prefix="sru"/>

  5. Edit the unAPI-SRU sitemap.xmap to set the address of your SRU server:

    <global-variables>
    <sruserver>
        http://yazproxy.somewhere.edu:9000/srw/zserver/zdb
    </sruserver>
</global-variables>

    Test the Cocoon interface to be sure it can retrieve records from SRU.

  6. Modify your OPAC full record display to include the required unAPI elements.
  7. Test with Xiaoming Liu’s Greasemonkey unAPI script or Ed Summers’ unAPI Validator.

If you would like to use some other field than rec.id to retrieve the record from the SRU server, you can modify the template for the SRU search url:

<map:generate src="{global:sruServer}?version=1.1&operation=searchRetrieve   &query=rec.id%3D{request-param:id}&maximumRecords=1   &recordSchema={request-param:format}" label="content"/>

You can test the unAPI component without an SRU server by commenting out the generator above in sitemap.xmap, and uncommenting the one that retrieves a local record. Of course, you’re then limited to the sample records provided in the samples directory. In this case the only available record id is “fred”.

Internals

The Cocoon component makes use of flowscript to manage the response. Have a look at flowscript/unapi.js to see how this works: it looks at the request parameters and routes the request to the appropriate pipeline. If the request is invalid, it sends the appropriate status code. If it tried to retrieve a record from the SRU server, it examines the response to determine whether a record was in fact returned, indicating that the record id is valid.

Cocoon depends on the SRU server to generate the record in the appropriate format. By default YAZ Proxy can generate marcxml, mods, and dc records, using XSLT stylesheets to produce the latter two. These formats are hard-coded in unapi.js and in xml/formats.xml; if you want to offer other formats, you’ll have to modify these files (as well as providing appropriate stylesheets).