[RFC] JSON Representations

[jtwalraven]

OpenSearch allows for standardization of search results metadata and descriptors to allow consumers (such as web browsers) to autodiscover and utilize search results. As many APIs are increasingly using some form of JSON, I wanted to codify the OpenSearch representation for the top hypermedia specifications. This would apply to the autodiscovery and response metadata.

At the moment I only had time to write out the HAL+JSON representation, but figured that it would be good to get comments and feedback before moving on to the other representations.

[epugh]

I just stumbled across this PR, as I'm working on adding OpenSearch as a understood format for https://github.com/o19s/quepid, a tool for measuring search quality. I'd been thinking that handling JSON versus XML would fit where the web is heading, so this is really cool. Are you interested in feedback on what you've done? I'm going to dig more into your examples/json-response.json example.

[dewitt]

I had a minute to go back and clear out some PRs and started reading this myself. I'm definitely supportive of publishing a canonical example of JSON serialization for all things OpenSearch, just as long as we can reach consensus about what "canonical" means for JSON.

Any opinions about how to reach that consensus?

(My original goal was to do a better job formally splitting out the abstract concepts from the serialization formats, but like a lot of things OpenSearch, that fell by the wayside when I changed jobs 15 years ago...)

[epugh]

I've never really participate in any kind of standards process, so I'm probably the last person to ask. I'm happy to kibbitz on what someone proposes, and maybe I can provide more value by actually writing code to consume that JSON representation, and that might provide feedback?

[dewitt]

I posted over on the OpenSearch group to get some more eyes on this proposal.

[ajturner]

Thanks for the ping on this @dewitt.

@JTWalraven This is an interesting proposal. My first question is if you can add some clarity on how the HAL+JSON resource is discovered?

One of the elegant aspect of OpenSearch is that it uses the HTML <Link> metadata for autodiscovery from a well-known resource (i.e. the website URL) to the OpenSearch definition for querying. I don't see this illustrated in your RFC. Would there be a HAL+JSON link from the website url?

That said, may be misunderstanding HAL where it is a response from the original URL (instead of HTML). Is this representation only used within a JSON response such as from a JSON-based REST API?

[jtwalraven]

Hey, sorry for the delayed response, been catching up on a few things.

@epugh Any feedback is appreciated 😄 And an implementation would be great!

@dewitt Agree with the consensus on "canonical". I chose HAL+JSON as a starting point as it makes it a little easier to understand how this might be used in a real world REST resource. I figured the way this would probably work is that there would be a general JSON representation and then examples demonstrating the various JSON representation specs: HAL, Siren, JSON-LD, etc.

@ajturner The resource is discovered using links like in HTML or ATOM. The following resource might provide a better overview: https://apigility.org/documentation/api-primer/halprimer Yes, your assumption is correct. There would be a search link from another resource (very likely the root resource as is the case for most search engines) that would have an href for an opensearch resource (either xml or json). For the time being, I figured I would separate those two concerns though (the resource descriptor and the search results description), since I wasn't sure what the interest level would be in the JSON descriptor and the XML version is well supported by browsers. I saw more of a use case for the search results description since you can embed it in your JSON media type result resource. If someone wants me to propose a JSON representation for the search descriptor, I can do that as well.

Thank you all for your interest and feedback!

[epugh]

Okay, so I have a project where I need to introduce a "Search Service", and I thought, hey, lets see how far we can get using OpenSearch. For giggles, I have deployed a proxy service that scrapes a website, www.hudexchange.info, and turns the results into what I think is OpenSearch response.

http://67.205.157.231:5000/engine/opensearch/hudexchange?q=hud&start=2

I had an earlier version that converted the results into Solr formatted JSON that I used with Quepid as a POC, you can see it here:

curl "http://67.205.157.231:5000/engine/hudexchange?q=charlottesville"

So, I'm not quite sure what next steps are... I think I want to layer in autosuggest...as well as spellcheck representations.

Behind this search api is Elasticsearch, and so I don't know how much the fact that it's Elasticsearch will need to bleed through.

If this goes well however, then I can add the JSON format to Quepid. I may play more with the XML format and see about integrating that as well.