Printer friendly page for this section
Implementation Options
The generic form of requests to the Router is
http://openurl.ac.uk/[action/[identifier:value/]+][?openurl_query]
where action defined the function the Router should perform, and one or more identifier:value pairs identify the user's institution. These parameters are included within the Router path (i.e. to the left of the ?) so they are part of the base URL, and are clearly separated from the OpenURL query string. This means that OpenURL queries can be generated by existing code in the form that they should be delivered to the end user's resolver: the Router does not require any special values to be added to the query, and the Router will not process or alter the queries you generate.
openurl_query is the normal OpenURL query string. Whatever query is provided here will be sent without alteration to the end user's resolver.
action
This defines the action that the Router should perform. This is optional and defaults to redirect, but a value should always be specified unless using the simplest form of request, e.g. http://openurl.ac.uk/?genre=journal&issn=0001-5903
- redirect
- Default option. The HTTP response is a redirect to the appropriate resolver for the user: this is the action that should be used whenever the Router is used as the target of OpenURL links presented to users. Suitable for GET requests; an OpenURL query string should normally be included in these requests.
- button
- Used as a request for the appropriate button image for the link, e.g. in the src attribute of an <img> tag. No query string should be provided.
- lookup
- A request for a registry lookup. An XML response details the base URL of the end user's resolver, the appropriate button image and "alt" text for the image. No query string should be provided. This can be used to retrieve details for a user, e.g. as part of a login/session initialization procedure; you can then provide links direct to the user's OpenURL resolver in whatever form you wish. Because this HTTP request will originate from your server and not the user's browser, at least one identifier/value must be provided for the Router to identify the user's institution. See below for more information about registry lookups.
identifier/value pairs
These help to identify the user's institution. In particular a UK federation scope will avoid the need for an IP address check, ensuring access to users' resolvers when working away from their institution, and avoiding the risk of slow or unsuccessful reverse DNS lookups.
- ukfed
- The UK federation scope of the end user's organisation.
- ip
- The end user's IP address. This is not necessary (but is harmless) when the request originates from their browser (e.g. if a link to the Router is placed in your user interface). It is intended for requests with a lookup action.
- dns
- The end user's domain name. This is not necessary when the request originates from their browser (e.g. if a link to the Router is placed in your user interface) though may give a faster response where a reverse DNS lookup would be required. It is primarily intended for requests with a lookup action.
- athens (backwards compatibility)
- Requests containing Athens usernames or institutional identifiers will continue to work after August 1st 2008, however this behaviour is deprecated. Please use UK federation scopes instead.
We will consider adding other identifier schemes that are useful to the community.
Example requests
Simple form of request that can be used for an OpenURL link in a web page. The Router responds with a redirect to the end user's OpenURL resolver, found from the IP address of the request or via the value set by the user in the WAYF.
http://openurl.ac.uk/?genre=journal&issn=0001-5903
http://openurl.ac.uk/redirect/?genre=journal&issn=0001-5903
A request that provides a button image for a link:
http://openurl.ac.uk/button/
A request suitable for an OpenURL link (above) and a button image (below), which specify the UK federation scope:
http://openurl.ac.uk/redirect/ukfed:ed.ac.uk/?genre=journal&issn=0001-5903
http://openurl.ac.uk/button/ukfed:ed.ac.uk/
Sample HTML for a link:
<a href="http://openurl.ac.uk/redirect/ukfed%3Aed.ac.uk/?genre=journal&issn=0001-5903">
<img src="http://openurl.ac.uk/button/ukfed%3Aed.ac.uk/" alt="find full text"></a>
Registry lookups
A registry lookup enables you to retrieve details of the end user's OpenURL resolver base URL, plus the preferred button image and "alt" text. This can be performed as often as required to construct OpenURL links, but to reduce your server load it probably makes sense to perform it when initialing a user session, and possibly linked to login procedures that handle UK federation authentication and/or IP address information.
A registry lookup would probably require more work to implement and simply using the OpenURL Router to redirect end users to their resolvers, but it does provide flexibility. In particular, the Router only redirects GET requests; if you wish to use POST requests to resolvers then a registry lookup would provide you with the correct URL for each resolver. You might also wish to consider caching lookup results, so OpenURL links can be provided in the event of the Router being temporarily unreachable.
Lookup requests take this form:
http://openurl.ac.uk/lookup/ukfed:ed.ac.uk/ip:111.112.113.114/dns:eg.ac.uk/
with ukfed, ip and dns values identifying the user's institution (see above). We recommend that you provide as many identifiers as possible.
The response is XML:
<?xml version="1.0"?>
<or:lookup xmlns:or="http://openurl.ac.uk/xmlns/">
<or:success>true|false</or:success>
<or:name>institution_name</or:name>
<or:resolver>resolver_url</or:resolver>
<or:button>button_url</or:button>
<or:alt>button_alt</or:alt>
</or:lookup>
- success
- true when the end user's OpenURL resolver was found, otherwise false. If not successful, the other tags will have no content; the Router can provide solutions where no resolver is found.
- institution_name
- The name of the institution that the end user belongs to.
- resolver_url
- The URL of the end user's OpenURL resolver, i.e. the base URL to be used for OpenURL links offered to the user.
- button_url
- The URL of the preferred button image for the user's OpenURL resolver. We strongly advise that this image be used. Most resolver administrators have a strong preference for this image being used; they wish their investment in their resolver to be returned by maximum use, and a consistent button image provides continuity to OpenURL links that may appear in many different user interfaces.
- button_alt
- "Alt" text for use with the button image. For users of non-visual browsers this can provide the same continuity of OpenURL links enjoyed by users who can see the consistent button image.
