UnAPI service

From refbase

This document describes the unAPI service as supported by refbase.

unAPI

refbase-0.9.0 or greater supports the unAPI standard which provides a common means to advertise, automatically discover and extract metadata, formats and/or files that are associated with contents displayed on a website.

The unAPI home page explains unAPI as follows:

"unAPI is a tiny HTTP API for the few basic operations necessary to copy discrete, identified content from any kind of web application."
"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."

A good overview of unAPI is given by Dan Chudnov et al. in Ariadne Magazine, issue 48: "Introducing unAPI".

refbase advertises the bibliographic citation and export formats that are available for a given database record via it's unAPI service. This allows clients to automatically discover and extract bibliographic data from a refbase database.

About the refbase unAPI implementation and usage examples

This section explains the refbase unAPI service and gives some working examples of an online refbase server:

All refbase web pages feature an unAPI autodiscovery link in the HTML <head>:

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

This informs an unAPI-aware client about the base URL of the unAPI service which in turn allows the client to get a list of all output formats that are supported by the refbase unAPI service (in XML format):

unapi.php

Individual database records are identified on refbase web pages using the <abbr> HTML tag, here's an example:

<abbr class="unapi-id" title="https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520"></abbr>

See the HTML source of this example page to get an idea of how this looks in real.

Using these embedded unAPI IDs, an unAPI-aware client can get a list of all formats available for a given database record (in XML format):

unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520

The client can now grab the preferred format for a particular record by specifying a suitable value within the format parameter. Here's an example URL for the RIS format:

unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=ris

Example URLs for other export and citation formats supported by the refbase unAPI service:

unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=bibtex
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=endnote
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=atom
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=mods
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=oai_dc
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=srw_dc
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=srw_mods
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=html
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=rtf
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=pdf
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=latex
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=markdown
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?record=21520&format=text

The refbase unAPI service also happily accepts identifiers which point to multiple records, e.g., try these unAPI requests:

unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?records=1-12,24,173-182,198,340,435,438,654&format=ris
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?records=1-12,24,173-182,198,340,435,438,654&format=rtf
unapi.php?id=https://refbase.ipoe.uni-kiel.de/refs/show.php?records=1-12,24,173-182,198,340,435,438,654&format=pdf