-
Notifications
You must be signed in to change notification settings - Fork 4
OFS REST API
List of contents:
[TOC]
The OFS request format is compliant with the OpenSearch specification, with its time and geo extensions, plus a few other extensions defined herein. The request format is fully defined in section 2 below, and is also described by the OFS OpenSearch Description Document. This is an XML document, as required by the OpenSearch specification, which defines the meaning and syntax of search requests.
Three OFS response formats are provided - rss, json and html - see section 3. The rss format is compliant with the OpenSearch specification. The default format is json - which is a format that is not used by OpenSearch but is nevertheless very popular.
Requests are made using the HTTP GET command, as follows:
http://hostname:8080/OFS/REST?q={searchTerms}&pw={startPage?}&size={count}&exclude={OFS:exludedTerms}&bbox={geo:box}&dtstart={time:start}&dtend={time:end}&norepo={OFS:repoList}&noindex={OFS:noIndexList}&format=html
Where each of the terms in braces is a placeholder for some value as defined below.
The definition of each of the terms in braces is provided in the specification that defines the respective xml namespace, viz:
For the default namespace: OpenSearch Version 1.1
For the "time" namespace: OpenSearch Time Extension Version 1.0
For the "geo" namespace: OpenSearch Geo Extension Version 1.0
For the "OFS" namespace: --- this document.
For convenience, the meaning of all the relevant terms from the cited specifications is shown below.
pw={startPage} where startPage is an integer (starting at 1 for first page)
size={count} where count is an integer number of hits per page (per search engine)
exclude={OFS:exludedTerms} where {OFS:excludedTerms} is a URL encoded list of space separated terms. Use double quotes (%22) around exact phrase matches. NB the exclusion of terms is applied to the snippets of matching text, not the whole document, and so must appear in the same field as the matching text, normally in the same sentence.
bbox={geo:box} where {geo:box} is a comma separated list of numbers: minLon, minLat, maxLon, maxLat forming a bounding box.
dtstart={time:start} applies a time filter to the field "dcterms:valid" in form
2017-10-23 or 2017-10-23T12:02:34
dtend={time:end} applies a time filter to the field "dcterms:valid" in form
2017-10-23 or 2017-10-23T12:02:34
NB Do not use dtstart or dtend if the repository being search does not
have a date field associated with each document.
norepo={OFS:repoList} Exclude searching of named repositories, where {repoList} is a comma separated list of repo names.
noindex={OFS: indexList} Exclude searching of specific indexes on specific repository name, where {indexList} is slash separated list of indexes to ignore on the specified repository name, comma separated between repo names, e.g. &noindex=repo1/index1/index2,repo2/index3/index4
format=rss, json or html.
Search for the two individual terms "hello" and "world". Note the default format of responses is json:
http://localhost:8080/OFS/REST?q=hello+world (URL encoding: "+" represents space)
or
http://localhost:8080/OFS/REST?q=hello%20world (URL encoding: "%20" represents space)
Search for the phrase "hello world":
http://localhost:8080/OFS/REST?q=%22hello+world%22 (%22 represents double quotes)
Search for "hello" excluding the word "world" near "hello" (i.e. in the returned "snippet")
http://localhost:8080/OFS/REST?q=hello&exclude=world
Same with request response in rss format:
http://localhost:8080/OFS/REST?q=hello&exclude=world&format=rss
Same with request response in HTML format:
http://localhost:8080/OFS/REST?q=hello&exclude=world&format=html
Example of search between two dates:
http://localhost:8080/OFS/REST?q=hello&dtstart=2018-08-25&dtend=2018-08-30
Example of search between two date-times
http://localhost:8080/OFS/REST?q=hello&dtstart=2018-08-25T12:00:00&dtend=2018-08-30T18:00:00
Example of excluding two repositories called REPO1 and REPO2:
http://localhost:8080/OFS/REST?q=hello&norepo=REPO1,REPO2
JSON is the default format. The JSON format is illustrated by the example below:
{"numberOfResults":1,"results":[{
"dc:title":"This is the title",
"OFS:link":"http://somehost:3000/some_path/document.html",
"OFS:matchingText":"He woke up and said, Hello World!",
"OFS:repoName":"REPO1",
"OFS:repoIndex":"index1/type1",
"dc:date":"2018-02-18T17:43:50.558Z"
},
{...other results...}]
}
The RSS response format is in accordance with the OpenSearch specification, with extensions defined herein. The REST service uses the template below to create RSS responses:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:OFS="http://dstl.gov.uk/OpenFederatedSearch/1.0/">
<channel>
<title>{OFS:service_title}: {opensearch:searchTerms}</title>
<link>{OFS:requestURL}</link>
<atom:link rel="search"
href="{OFS:opensearchdescription_URL}"
type="application/opensearchdescription+xml"
title="Open Federated Search" />
<description>Search results for "{opensearch:searchTerms}" from {OFS:service_title}</description>
<opensearch:totalResults>{opensearch:totalResults}</opensearch:totalResults>
<opensearch:startIndex>{opensearch:startIndex}</opensearch:startIndex>
<opensearch:Query role="request" searchTerms="{opensearch:searchTerms}" startPage="1" />
<item>
<title>{dc:title}</title>
<link>{OFS:link}</link>
<description>{OFS:matchingText}</description>
<pubDate>{dc:date}</pubDate>
<OFS:repoName>{OFS:repoName}</OFS:repoName>
<OFS:repoIndex>{OFS:repoIndex}</OFS:repoIndex>
</item>
<!-- ... -->
</channel>
</rss>
Where each of the terms in braces is a placeholder for some value as defined below.
The definition of each of the terms in braces is provided in the specification that defines the respective xml namespace, viz:
For the "opensearch" namespace: OpenSearch Version 1.1
For the "dc" namespace: Dublin Core
For the "OFS" namespace: --- this document, as follows:
{OFS:service_title} : A chosen description of the service, e.g. Open Federated Search on <some network>.
{OFS:opensearchdescription_URL} : The url of the location of the OpenSearch description (in XML) that describes this Open Federated Search system. This will be of the form: http://OFS_hostname:8080/OFS/FedSearch?action=opensearch.
{OFS:matchingText} : Some "snippets" from a matching document that contain the search terms.
{OFS:repoName} : The name of the repository that contains the matching document.
{OFS:repoIndex} : The name of the index that provided the match (optionally with a "type" added after a forward slash, viz: index/type). If a search engine does not provide this information the value "undefined" should be inserted by the OFS plug-in for that search engine.
The HTML format is almost the same as what a user would see in a web-browser for the same search using the OFS Web-application, except that hyperlinks to select the next page, first page and new search are not provided. The search terms are emphasised in bold red.
<html><head><style>em {color: red; font-weight: bold;}</style></head>
<body>Total 1 results<BR>
<div><A href="http://somehost:3000/somepath/document.html">Title of document</A><BR>
I woke up and said, <em>Hello World</em> ... <BR>
<small>REPO1/index1/type1  2018-03-03T15:19:10.085Z</small>
</div><BR>
... any other results each within <div>...</div>
</body></html>