Difference between revisions of "Umlaut full API"

Revision as of 16:09, 30 September 2008

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.

Accessing the API

The api can be accessed at the resolve/api action. For instance, if your umlaut is at umlaut.somewhere.edu/, 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.

By default, the API returns XML. To return json instead, include:

&umlaut.response_format=json

To return jsonp, wrapped in a javascript procedure call:

&umlaut.response_format=jsonp&umlaut.jsonp=desiredJavascriptFunctionName

API Response

<request_id>

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.

<context_object_xml>

Contains an OpenURL context object in XML serialization. May include enhanced citation metadata from Umlaut.

<complete>

When accessing Umlaut over an API, it's important to realize that the initial response from Umlaut may not include all Umlaut information. Umlaut continues to run services in the background that can generate responses and enhance metadata. <complete> will contain 'true' or 'false' depending on whether background services are still executing. Further elements in the response provide information on what is still executing, and how to retrieve further information.

<in_progress>

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).

<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.

<services_in_progress> lists the ServiceTypeValues that may still have responses coming, that may not be complete. A list of all possible ServiceTypeValues in a default Umlaut installation can be found in the [Umlaut code].

<service_statuses>

This block provides information on the internal service plug-ins involved in this Umlaut request, and what their status is. In most cases, an API client will not need this information.

<status> can be one of:

• in_progress : Currently executing
• queued : Background service which is queued up, but not yet running.
• succesful : completed succesfully (may or may not have generated any responses)
• failed_fatal: A fatal error condition was encountered, for instance a bug in Umlaut code.
• failed_temporary: An error condition was encountered, but Umlaut may try to run the service again, the error was not fatal, for instance an external service timed out.

These constants are defined in dispatched_service.rb

If the <status> is failed_fatal or failed_temporary, there may be error information in an <exception_info> block.

<responses>

The meat, the actual response or 'target' data generated by Umlaut. These responses are grouped by ServiceTypeValues. A given ServiceTypeValue identifies a certain type of service, like full text, or library holdings. The list of possible ServiceTypeValues in a default Umlaut installation can be found in the relevant Umlaut distribution data file service_type_values.yml

The <responses> block contains 0 or more <type_group> blocks. Each type_group has a name attribute identifiying the ServiceTypeValue, also provides you with user-displayable label for this type, and tells you if all services that generate this type are complete or not:

<type_group name="abstract">
  <display_name>Abstract</display_name>
  <display_name_plural>Abstracts</display_name_plural>
  <complete>true</complete>

  [...]
</type>

Each type_group will have one or more <response> blocks in it. A <response> represents an individual piece of data generated by umlaut. The trick here is that individual elements inside <response> can very between differnet service types, or even between different