Implementing the OpenSearch Protocol

How I Learned About OpenSearch

I learned about the OpenSearch Protocol a few years ago. I was working at a company that wanted to expose a RESTful search API. Implementing the OpenSearch protocol seemed like a perfectly reasonable approach to take. After all, OpenSearch has been around since 2005. But don't let it's age betray you: that's part of the beauty of it. You see, when it comes to implementing RESTful APIs, if you can discover a protocol that already exists, then the older the better: it means that pre-existing clients and libraries might already exist.

Some OpenSearch Clients

The Wikipedia entry gives a little more history to it and provides some screenshots of it's support in Firefox.
Although I've never used it, we discovered that Sharepoint supports OpenSearch.
I'm partial to Mac's Alfred in which it supports discovering OpenSearch implementations. (Unfortunately it doesn't support fetching search suggestions, but it's straightforward to implement a custom workflow to do this.)
I believe surfraw also supports OpenSearch.

OpenSearch Protocol Pre-requisites

There are a few pre-requisites to implementing the protocol:

You must have an existing endpoint that renders search results. Ex: this website's endpoint is https://nonattachment.net/search?q=opensearch.
(Optional) You may have an existing endpoint that fetches search suggestions. To implement the protocol the suggestions have to be returned in a specific format. Ex: this website's endpoint is https://nonattachment.net/suggest?q=opensearch. The minimal format of the response will look something like this:
```
   ["query", ["suggestion1", "suggestion2", "etc."]]
```
This can optionally be extended to include descriptions and query URLs. Your suggestions endpoint should probably be limited to returning no more than 10 suggestions.

Implementing the Opensearch Protocol

The first thing we'll need is to define an OpenSearch Description XML document.

OpenSearchDescription XML Document

This document provides a name, description, input encoding, and image URL for our search engine. It also provides the two search and suggestion endpoints described above. And finally we add a link to itself:

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">

  <ShortName>
    Non-Attachment
  </ShortName>

  <Description>
    Search the nonattachment.net blog
  </Description>

  <InputEncoding>
    UTF-8
  </InputEncoding>

  <Image
      width="16"
      height="16"
      type="image/x-icon">
    https://nonattachment.net/favicon.ico
  </Image>

  <Url
      type="text/html"
      template="https://nonattachment.net/search?q={searchTerms}"/>

  <Url
      type="application/x-suggestions+json"
      template="https://nonattachment.net/suggest?q={searchTerms}"/>

  <Url
      rel="self"
      type="application/opensearchdescription+xml"
      template="https://nonattachment.net/osd.xml"/>

</OpenSearchDescription>

Note that this is just this website's OpenSearchDescription document. More features can be added such as supporting search results in RSS or ATOM (allowing your users to be notified whenever a new result matches their search).

Auto-discovery

The last step is trivial. In the <head> section of your web pages put a link to your OpenSearchDescription document. Example:

<link
  rel="search"
  href="/osd.xml"
  title="Non-Attachment"
  type="application/opensearchdescription+xml"/>

Conclusion

I find it best to test with Firefox as it supports search suggestions. Under Settings -> Search -> Search Bar I always preferred having a separate search bar because this can display all your search engines and it's possible to change the default search engine. If you navigate to your website and the search link is in the <head> tag, then Firefox should be able to discover your search engine.

Happy searching!