SearchAPI for the Ahiqar Project
Preliminaries
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14, RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.
This document is licensed under CC-BY-ND-4.0 (via SPDX).
The style of this documentation is adapted from OpenAPI 3.0.2 specification.
Status of this Document
The current version of this document is 1.0.0
.
The version number will be applied according to Semantic Versioning 2.0.0.
Definitions
Cardinalities
Cardinality | Description | REQUIRED |
---|---|---|
1 | exactly one | yes |
+ | one or more | yes |
? | zero or one | no |
* | zero or more | no |
Data Types
Type | Description |
---|---|
[…] | array |
string | a sequence of characters, MAY be empty |
URI | a valid URI, see URI Syntax |
int | a non-negative Integer value |
URI Syntax
The URI Syntax is used according to the one described at IIIF.
About this SearchAPI
The used query syntax and objects are prepared alike Elasticsearch`s Search API (v7.13), but not completely similar.
This API is a standalone development especially for the Ahiqar project.
Endpoint
https://ahikar.sub.uni-goettingen.de/api/search
Search Request
POST
the following object to the endpoint to execute a search.
Field Name | Cardinality | Type | Description |
---|---|---|---|
query | 1 | Simple Query String Object | main object for setting up the query |
from | 1 | int | zero-based index of start item in response |
size | 1 | int | number of hits to return |
Simple Query String Object
This object is specified according to the Elasticsearch Query DSL.
Field Name | Cardinality | Type | Description |
---|---|---|---|
simple_query_string | 1 | Query String Object | main query object |
Query String Object
Field Name | Cardinality | Type | Description |
---|---|---|---|
query | 1 | string | search query see query string rules and Lucene syntax |
Query String Rules
- An empty query string is not allowed.
- Wildcard only seach is not allowed.
- Multiple terms are separated by whitespace.
- A whitespace character as term deliminator is equal to
AND
by the implementation. - Leading wildcard is possible.
Sample Request
{
"query": {
"simple_query_string": {
"query": "term termina*"
}
},
"from": 0,
"size": 10
}
Search Response
Field Name | Cardinality | Type | Description |
---|---|---|---|
hits | 1 | [Hits Object] | search result hits |
took | 1 | int | time in ms search execution took on back end side |
Hits Object
Field Name | Cardinality | Type | Description |
---|---|---|---|
total | 1 | Total Object | properties of the hit list |
hits | 1 | [Hits Array] | sequence of hits (ordered by score) |
Total Object
Field Name | Cardinality | Type | Description |
---|---|---|---|
value | 1 | int | number of total hits (in this scope: pages) |
manifests | 1 | int | total number of distinct manifests in hits |
matches | 1 | int | total number of matches (equal to the sum of all values from occurrencesOnPage ) |
relation | 1 | string | eq (from Elasticsearch), means that there are exactly this number of total hits available |
Hits Array
This describes a single object from the hits
array that MUST be present but MAY be empty.
Field Name | Cardinality | Type | Description |
---|---|---|---|
item | 1 | URI | path to the item context, w/o base uri |
label | 1 | string | label of the manifest see TextAPI |
n | 1 | string | page number as in tei:pb/@n see TextAPI |
matches | 1 | [ match object ] | array of matched strings according to the search terms (useful to present matches when using wildcards). Cannot be empty by definition. |
Match Object
Field Name | Cardinality | Type | Description |
---|---|---|---|
term | 1 | string | exact matched word or phrase |
occurrencesOnPage | 1 | number | number of occurrences of this exact match in scope (page) |
Sample Response
{
"hits": {
"total": {
"value": 2,
"relation": "eq",
"manifests": 2,
"matches": 5
},
"hits" : [ {
"item": "/api/textapi/ahikar/syriac/3r678-186v/latest/item.json",
"label": "Cod. Arab. 236 Copenhagen",
"n": "123v",
"matches": [
{
"term": "term",
"occurrencesOnPage": 3
},
{
"term": "terminal",
"occurrencesOnPage": 1
}
]
}, {
"item": "/api/textapi/ahikar/syriac/3r678-126r/latest/item.json",
"label": "Cod. Arab. 236 Copenhagen",
"n": "126r",
"matches": [
{
"term": "terminal",
"occurrencesOnPage": 1
}]
} ]
},
"took": 678
}