Oh those librarians! I have encountered them before, dealing with OAI-PMH, a spec that mandates how to declare your XML namespaces in the documents you hand around.
They have another one: OpenURL.
This is all about these two posts:
Naturally, the boss would like all of this cool stuff available on our site at Biodiversity.org.au. I have noticed that scientists are a trifle competitive.
OpenURL seems to be a way to embed a data record in a querystring. Nasty. Equivalently: it is a set of well-known querystring parameters pertaining to things available in libraries, specifically scientific books, journals, and journal articles. Part of the standard is a
- OpenURLs for books are described here.
- OpenURLs for journal and journal articles are described here.
The important bits are the metadata fields
- url_ver=Z39.88-2004 – this is an OpenURL version 1.0 querystring
- rft_val_fmt=info:ofi/fmt:kev:mtx:journal- we are using the journal openurl format
The other important bit is the DOI field, which both formats include.
COinS is a way to attach metadata to blocks of text on an HTML page. You have a
span element with a
class and a
class specifies that this is a coin and what format/namespace the coin belongs to. Not sure where the spec for that is, or the list of well-known values. The class for OpenURLs is
title contains the data itself – in this case, the OpenURL.
Finally, webhooks. As far as I can tell, a webhook is simply a url that you can call with some parameters. The spec (such as it is) insists on POST requests. I don’t know why. The spec also does not state what should be – you know – *in* the post request. I rather suspect that it assumes
application/www-form-encoded key/value pairs and fails to say so because someone or other is not aware that a POST can contain anything. And it doesn’t seem to specify any way of specifying what the parameters are.
It really seems like someone has re-discovered web services and gotten excited about ’em. The only thing of note is that there’s a client/server switcheroo. When you register a webhook url with google docs, conceptually google is “upstream”, but mechanically it is a client calling a service you implement. it’s just a push subscription.
For both the OpenURL specification and for these webhook things in general, it seems to me that calling ’em a webservice and using WSDL to document them is the way to go. Hence my whinge about librarians at the start – like the OAI-PMH spec, the guys at OpenURL don’t seem to be aware of existing standards. In particular, if it was defined at the WSDL level, they wouldn’t need to go into detail about the fact that you need to URL-encode the values: it’s implied by the binding type. Having words in the OpenURL spec explaining url encoding is exactly the same kind of mistake as having words in the OAI-PMH spec specifying how to declare the oai namespace in your XML.
So Rod Page has a OpenURL resolver service. When it resolves an OpenURL, it has an interface by which the user can go “Yes, I meant *this one*” . That interface looks at the referring entity identifier on the OpenURL, gets the WebHook (from where? Is in in the OpenURL? There’s no spot for that in the
info:ofi/fmt:kev:mtx:journal format. Is it in some other querystring parameter? ) and sends to that webhook … I don’t know. Possibly the OpenURL with all the fields filled in. Or maybe with just the DOI, which is the bit that this demo was interested in.
In other words: I am rather getting the impression that we have a custom bit of software that talks to another custom bit of software.
Oh well. Adding COinS to our publication records, and even to internal links, is doable. A snag is that the firefox plugin does not display the content of the span but replaces it with an image. Gahh! Who TF thought that that was a good idea??? The idea of COinS is that you wrap something – the reference citation or whatever. If the firefox plugin is running, it will actually not show the user the citation text if it’s wrapped. Goddamn …
Ok. How about a service that allows a client to attach an OpenURL to a publication record? Damn it, damn it, damn it: the webhooks docs states specifically that it has to be a
POST request. Why? I don’t know. An OpenURL resolved against a base service URL is a
GET request with a querystring. 3 options:
- Ignore the “webhooks” guys and accept the parameters as a
- Ignore the OpenURL guys and take a
POSTwith the parameters in the OpenURL as
www-form-encodedparameters. That is: not as a URL as such.
- Accept a www-form-encoded form with a single in-house parameter named “openURL”, which has to be an openURL … which may or may not have to be be URL-encoded. This satisfies no-one, and involved making up our own spec on top of these others
All of which could have been avoided if they’d used WSDL and not specified that OpenURLs must be URLs, but were WSDL “Messages”. And if the WebHooks guys had admitted that a WebHook is when you allow a user to give you a URL with which to do this:
<wsdl:definitions> <wsdl:import namespace="http://hookspec"/> <wsdl:service name="Freds callback"> <wsdl:port name="Callback" binding="hookspec:httpBinding"> <http:address location="http://fred.com/webhook1"/> </wsdl:port> </wsdl:service> </wsdl:definitions>
Maybe I’ve gotten it all wrong. Wouldn’t be the first time.
UPDATE: found the spec. It’s at http://www.niso.org/kst/reports/standards?step=2&gid=None&project_key=d5320409c5160be4697dc046613f71b9a773cd9e, obviously.