Commit fb588719 authored by Mathias Goebel's avatar Mathias Goebel 🎠
Browse files

feat: improved docs for search

parent 7fb6f5bf
......@@ -3,10 +3,55 @@ title: SearchAPI Specification
version: 0.0.1
---
# Search
# 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](https://tools.ietf.org/html/bcp14),
[RFC2119](https://tools.ietf.org/html/rfc2119) and
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear
in all capitals, as shown here.
This document is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
The style of this documentation is adapted from [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
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](https://semver.org/spec/v2.0.0.html).
## 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](#uri-syntax) |
| int | a non-negative Integer value |
## About this SearchAPI
The used query syntax and objects are prepared alike [Elasticsearch`s Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html), but
not completely similar.
This API is a standalone development especially for the Ahiqar project.
## Endpoint
`https://ahikar.sub.uni-goettingen.de/api/search`
......@@ -16,16 +61,23 @@ not completely similar.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| query.simple_query_string.query | 1 | string | search query [see Lucene syntax](https://lucene.apache.org/core/8_9_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description) |
| from | 1 | number | start item in response |
| size | 1 | number | number of hits to return |
| query.simple_query_string.query | 1 | string | search query see [query string rules](#query-string-rules) and [Lucene syntax](https://lucene.apache.org/core/8_9_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description) |
| from | 1 | int | start item in response |
| size | 1 | int | number of hits to return |
### Query String Rules
* An empty query string is not allowed.
* Wildcard only seach is not allowed.
* Multiple terms separated by whitespace.
* A whitespace character as term deliminator is equal to ` AND ` by the implementation.
* Leading wildcard is possible.
### Sample Request
```json
{
"query": {
"simple_query_string": {
"query": ""
"query": "term1 term2 terminat*"
}
},
"from": 0,
......@@ -38,7 +90,7 @@ not completely similar.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| hits | 1 | \[[Hits Object](#hits-object)\] | search result hits |
| took | 1 | number | time in ms search execution took back end side |
| took | 1 | int | time in ms search execution took back end side |
### Hits Object
......@@ -51,16 +103,15 @@ not completely similar.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| value | 1 | number | number of total hits |
| value | 1 | int | number of total hits |
### Hits Array
This describes a single object form the `hits` array.
This describes a single object form the `hits` array that MUST be present but is MAY be empty.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| item | 1 | IRI | path to the item context, w/o base uri |
| item | 1 | URI | path to the item context, w/o base uri |
| label | 1 | string | label of the manifest [see TextAPI](../text-api-specs/#manifest-object) |
| n | 1 | string | page number as in `tei:pb/@n` [see TextAPI](../text-api-specs/#item-object) |
......@@ -68,9 +119,9 @@ This describes a single object form the `hits` array.
```json
{
"hits" : {
"total" : {
"value" : 2
"hits": {
"total": {
"value": 2
},
"hits" : [ {
"item": "/api/textapi/ahikar/syriac/3r678-186v/latest/item.json",
......@@ -82,6 +133,6 @@ This describes a single object form the `hits` array.
"n": "126r"
} ]
},
"took" : 1
"took": 1
}
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment