User:Mconnor/Pending/SearchUpdates

Update URL

A new URL type to OpenSearch descriptors: application/x-opensearch-update

Example:

<Url type="application/x-opensearch-update"
     template="https://www.foo.com/searchupdater?version={version}"/>

version will default to 0 if there is no <Version> element.

On first use of a search descriptor after the expiry date (defined in the <Expires> element, defaults to 0 if not present), the UA will do a GET request to the URL specified, with the version attribute substituted for {version}. (i.e. https://www.foo.com/searchupdater?version=foo). If there are no changes, return an HTTP 304 Not Modified response to the client. The UA should update the expiry to the minimum next interval on this response. In order to minimize failed attempts, any errors will be treated as no update available.

If an update is available, the new search descriptor should be returned by the server and parsed by the UA. The new version will be used in place of the original version. If expires is less than the minimum update interval, that value should be bumped to satisfy that requirement. If there is no version provided, we should increment the version from the previous version. If the base updateURL is different, the update MAY (MUST) be rejected by the UA.

UAs providing a default set of descriptors may reset to a new default set and clear any updates as appropriate, and will check for updates for those defaults on first use as described above. This allows a change to updateURLs as needed.

Version element

Optional: Contains a version which is passed as part of the update URL

Parent: OpenSearchDescription Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. Requirements: This element may appear zero or one time.

Example:

<Version>47</Version>

Expires element

Optional: Contains an expiration time in standard timestamp format, used with update URLs

Parent: OpenSearchDescription Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. Requirements: This element may appear zero or one time.

Example:

<Expires>1222215762</Expires>

Forced Updates

If a UA navigates to a search descriptor served with application/opensearchdescription+xml on the same origin (host+scheme+port) as the updateURL, the UA will download and parse the descriptor file. If the criteria below are met, the UA should update the local copy transparently.

Update Criteria:

The Update URL MUST match exactly.
If the local copy has a <Version> element, the remote copy must be a newer version.

Example Search Descriptor with Update support

<?xml version="1.0"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <ShortName>FooBar</ShortName>
    <Description>FooBar Search</Description>
    <Image height="16" width="16" type="image/x-icon">
      http://foo.com/favicon.ico
    </Image>
    <Url type="text/html"
         method="get"
         template="http://foo.com/search?search={searchTerms}" />
    <Url type="application/x-suggestions+json" 
         method="get" 
         template="http://foo.com/suggestions?search={searchTerms}"/>
    <Url type="application/x-opensearch-update"
         template="https://www.foo.com/searchupdater?version={version}"/>
    <Version>42</Version>
    <Expires>1222311335</Expires>
</OpenSearchDescription>