200
edits
Changes
no edit summary
=WARNING: This is Outdated Documentation!!!!=
'''THIS IS OUTDATED DOCUMENTATION''' See new Umlaut documentation at http://github.com/team-umlaut/umlaut/wiki
---------
Umlaut has a complete api for resolve actions, which can be delivered in XML or json. For simple uses of embedding Umlaut content on a page, you may find the [[Umlaut partial html API]] or [[Umlaut partial html API javascript helper]] easier to use.
[[Category:Umlaut]]
= Accessing the API =
The api can be accessed at the resolve/api action. For instance, if your umlaut is at umlaut.somewhere.edu/, http://umlaut.somewhere.edu/resolve/api?
Append an OpenURL context object to that URL. (POST is also supported, including XML formatted context objects. Anything you can send to ordinary Umlaut resolve). You can also include the usual umlaut directive parameters. This is exactly what you'd send to the ordinary Umlaut link resolver base url for link resolver service in html; you are just replacing /resolve? with /resolve/api?
By default, the API returns XML. To return json instead, include:
</pre>
Umlaut's internal request id. API clients usually don't need this, but can be useful if you want a unique identifier for this OpenURL request. May also be useful if you want to call other Umlaut actions on this same OpenURL request, ensuring that Umlaut matches to the same request, by including ¨aut.request_id in your request.
== <context_object_xml> ==
This block will only be present when <complete> is 'false'.
<refresh_url> provides a url the client can request again to see further results. If the client user agent does not support cookies, then this refresh_url must be used to continue retrieving results from the same Umlaut request, instead of accidentally creating a new request. Even if your client does support cookies, using the <refresh_url> is safest--simply refreshing the URL you loaded initially may accidentally create a new request. (The refresh_url given includes an umlaut.request_id parameter to ensure connection to the proper request). '''note well:''' The URL, like any other data in XML, is XML-escaped, and needs to be un-escaped before using.
<requested_wait_seconds> is a request from Umlaut for the client to wait this many seconds before asking for more results. Umlaut has no way to enforce this, it's only a request. Please wait a reasonable amount of time to avoid overloading Umlaut however.
