Kevin Richards, March 2007 - Version 0.1
This folder contains the files required for a very simple LSID authority to resolve LSIDs that are contained within the data of a TapirLink provider.
The LSID authority works by specifying part of a TAPIR URL based on a parameterised query template. The query template must contain at least one filter condition bound to an "lsid" parameter. LSID clients will then call the specified TAPIR URL appending the "lsid" parameter. This call will return metadata for the respective LSID. The example given by default uses a query template that returns an RDF representation of DarwinCore using a filter where the "lsid" parameter must match the value of the GlobalUniqueIdentifier DarwinCore concept.
The LSID authority was created by taking the HTTP GET bindings of the LSID specification and interpreting them from the point of view of someone who is comfortable with implementing web sites and applications in technologies like ASP, JSP, Python and PHP. SOAP bindings and complex web service stuff are ignored. It is assumed that we are using PHP and have a PHP enabled web server, however porting the code to another technology would be easy enough.
LSID Authorities are quite simple. A client application "does something clever" with DNS in order to find an authority's domain (I'll talk about this a little later on). Once it has got the domain it appends "/authority/" to make a URL that it calls to retrieve a WSDL file. WSDL files can be quite complex but they have been written for us so we don't have to worry about them too much - we can use simple template files for them. The file the client gets back tells it how to access the getAvailableServices(LSID lsid) method. Because we are only dealing with the HTTP GET bindings here, this means it contains the URL the client must call to invoke this method.
The client calls the URL for the getAvailableServices(LSID lsid) method appending ?lsid=<theLSID> and gets back another WSDL file. This file contains the URLs that must be called for each of the methods associated with the LSID it passed in. Once the client has this list of URLs it calls the ones it needs to do things like get the metadata or data associated with this LSID. The client passes values to these calls by tacking them onto the end of the URLs just like an HTTP form submit where the 'method' attribute is set to GET. If you can write code to handle form submits you can handle these calls. To summarise:
It is not rocket science. It is just like writing regular interactive web pages.
The following things need to be done to get the authority working with your TapirLink data:
(assumes PHP and any required URL rewrite rules are already set up)
# This rule corrects invalidly formatted LSID authority calls (where the url has incorrectly appended /authority to the
# authority location, eg http://localhost/tapirlink/index.php/authority/)
RewriteRule ^(.+\/)index.php\/authority\/(.*) $1index.php$2
# This rule removes the resource name from after the .php file and adds it as a query parameter (eg from
# http://localhost/tapirlink/index.php/resource?... to http://localhost/tapirlink/index.php?dsa=resource&...)
# and it also corrects erroneus use of additional query separators appended to the URL
RewriteRule ^(.+\/)tapir.php\/([^\?\/]+)[\?\/]?(.*)[?](.*) $1tapir.php?dsa=$2(?3&$3)(?4&$4)
We can now run through the three actions that an LSID client will do, but using our web browser to check we are getting the right responses.
I assume you have installed IBM Launchpad in IE. In the configuration section of Launchpad set up an authority. This will need to be YourDomain.org (or whatever authority you want to use in your test LSIDs) and point to the URL we tested in point 1 above - "http://<YourDomain.org>/authority/". Now resolve an LSID of your choice. Something like "lsidres:urn:lsid:<YourDomain.org>:example:123" (depending on the data in the database you have linked to) should work OK.
If you have got this far you have succeeded in setting up and testing an LSID. Unfortunately they only resolve if the client knows the URL of the Authority. We need to do something with DNS so that clients can discover the authority location automatically. This is the "something clever" mentioned above and I refer you to the relevant section in the Perl stack tutorial for this. If you have access to your own DNS server then it is just a matter of making a new entry for your authority as described. If you don't have direct access then it is a matter of writing to someone who can do it for you.
This may take a while as you may have to get a systems administrator to set things up so once you have set it in motion you can think about the next stage - returning real data/metadata.
The code that accompanies this document consists of 6 things:
There is no error handling in this code. The specification explains how errors should be thrown in the HTTP GET binding and it is pretty simple - you just return them in the HTTP header. At a minimum you should return an error if the client requests your authority to serve an LSID it isn't responsible for. The first place to do this would be to throw an error in index.php if the LSID didn't match a regular expression that described your own LSIDs. i.e. if they had the wrong authority string or namespace.