Data API Response

jrochkind edited this page Jan 27, 2012 · 2 revisions

Umlaut has a full http API response for a /resolve action, containing pretty much all the information there is about the request, in XML or JSON.

note: The JSON version is a bit wonky, as internally we start with XML and automatically convert to JSON. If I were to start over, I'd start with JSON, and convert to simpler attribute-less XML instead.

However, for most cases, this is overkill, and you probably want the HTML Snippet API Response, or the JQuery Content Utility. But if you really do want the full API response, read on.

Accessing the API

The api can be accessed at the resolve/api action. For instance, if your umlaut is at,

Append an OpenURL context object to that URL. POST is also supported, including XML formatted context objects. 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:


To return jsonp, wrapped in a javascript procedure call:


API Response




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 &umlaut.request_id in your request.


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


<complete value="true">true</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.


          <service name="fulltext" />         
          <service name="holding" />         
          <service name="table_of_contents" />         
          <service name="highlighted_link" />         
          <service name="audio" />         
          <service name="holding_search" />        

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.

<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 id="ElsevierCover">
    <created_at>2012-01-04 16:38:26 UTC</created_at>

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 app/models/dispatched_service.rb

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

        <message>background service timed out (took longer than 30 to run); thread assumed dead.</message>

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. A type_group will only be present if it contains responses.

<type_group name="abstract">


<response id="86">
  <!-- Attributes really vary depending on particular service, this makes it kind of tricky to deal with in an API. See   documentation in ServiceResponse for conventions. Reccommend that you use umlaut_passthrough_url for url. Final destination url isis calculated on-demand by umlaut. -->

Each type_group will have one or more <response> blocks in it. A <response> represents an individual piece of data generated by umlaut. This is what most clients will be most interested in, but it's tricky to deal with because the contents of a <response> are quite variable. They can vary between responses for different ServiceTypeValues, and there can even be specialized data only in responses belong to a particular Service plug-in. All the data that Umlaut has is included here, including some really intended for internal use only.

However, don't despair, there are a few things you can count on. The <display_text> element will always include the label or heading that is to be used for the response. A <notes> element may be present with additional explanatory text. These alone, plus a linking url, will be enough for many clients. See ServiceResponse docs for keys used by convention.

Standard internal metadata includes a element which will contain the name of the service plug-in that generated this response. (Match to services listed in <service_statuses> above).

Linking url: <umlaut_passthrough_url>

You may see the <url> element in the response and be tempted to use it to send the user to this response. You are strongly cautioned not to do so. In the Umlaut architecture, urls can be generated on-demand when the user clicks on an element, not at time of original response (this is because even generating the url is sometimes an expensive operation). This means that the <url> element is not guaranteed to be there, and when it is there is not guaranteed to be accurate. On top of all that, the application of a proxy pass through won't be applied yet to the url found here.

You should instead use the <umlaut_passthrough_url> element. This will contain a URL pointing to your umlaut installation, of the form:

When this URL is accessed, Umlaut will redirect the user to the actual destination--after calculating that destination, and applying any proxy or other filters, etc. In some cases it may end up redirecting to the same destination as <url>, but in other cases it may be somewhat different, or may work even if <url> was not present.

Please use the umlaut_passthrough_url for linking.