Changes

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

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.

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

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.

This block will only be present when <complete> is 'false'.

<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 [[http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml Umlaut code]].

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.

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

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 [http://umlaut.rubyforge.org/svn/trunk/db/orig_fixed_data/service_type_values.yml service_type_values.yml]

</pre>

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.

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.

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.

Each ServiceTypeValue has other conventions for elements that will be present in that ServiceTypeValue. These are documented in [http://umlaut.rubyforge.org/api/classes/ServiceResponse.html ServiceResponse] in the Conventional Keys section.