API for Linkable References

(Donna Bergmark and Carl Lagoze, Final Version)
(previous version)

A linkable reference is a work which has at least one copy somewhere on the network, is findable, and we know how to find it. Here is a list of term definitions, the most important of which are "reference" and "citation". These are "creations" in the IFLA sense, and include both works and manifestations. Creations are referenceable; items are linkable because they have URLs.  One Creation may have many Items.  Furthermore, when we say "copy of a paper" we are really saying "Item of a Creation."  The two phrases are interchangeable.

Design for a Reference Linking API

This section is an attempt to answer the question, "In the ideal world, what would be the operational semantics to link in and out of an object? What methods would you want the object's linking surrogate to have?"  In the ideal world we should like to think of objects linking to each other, but for practical reasons we use proxies, or surrogates, to perform the linking semantics on behalf of the items they represent.

There would be (in the perfect world) only one surrogate per creation, but  in the real world we may not be able always to determine when two different sets of bibliographic data in fact represent a single creation.  Instead we assume that each item in a repository has a surrogate. Two different copies of the same paper will have two different surrogates, even if they belong to the same Creation, if they exist in two different repositories..

Note that our definition of an API is to list the methods that we would like linking proxies to support.  Each method contains a description of what sort of information is to be returned;  however, the precise format of input parameters and return values is left to a more detailed specification of the API, later on.

Here is the final cut of the API: 

The link from the FEDORA digital object to these external databases will be programmatic.

Question: since the surrogate is a FEDORA object, what would its URL look like? We are assuming that a name service, given a URN, would return a list of surrogate URLs.  But FEDORA objects have URNs (e.g. cornell.dli2/unique name of object) and not URLs.  I think it would be better if the handle service mapped the creation's URN to the list of surrogate URNs, each of which then held a URL to the archive item the surrogate is representing.

The Linking Service

This section addresses the question, "What would a reference linking service look like?"

One can think of the linking service within the context of something like Dienst or other retrieval service. The group at the University of Southampton is doing a lot of good work in this area. Once you have retrieved a paper and are viewing its full text, you ought to be able to access the references while reading the original paper. At the very least, a javascript will bring up the reference in a separate window, as it appears at the end of or within the document you are reading. If the reference is linkable, then the user should be asked whether to retrieve the reference. If the answer is yes, then the retrieval of the referenced object should occur asynchronously, while the user continues to read the original paper.

Another function of the linking service is that when you retrieve a paper (full text or not) you should be able to ask the service for citations of this paper, related papers, contexts of the citations, and so on. The linking API described here should support that goal.

The API described here might become part of a larger service; for example, it could be merged with collection services.  Or it could stand on its own as a reference linking service.

Using the API

One test of the API is to see if it can be used to construct a collection of surrogate objects in the first place. This page details the use of the API to construct such a collection. 
Source: $HOME/private/DLRG/ReferenceLinking/API.html 2000/03/27   Updated 2000/05/04-7-18 based on comments from Carl Lagoze.   Published: http://www.cs.cornell.edu/cdlrg/Reference%20Linking/APIforLinkableReferences/API.html