feat: improved docs for search

content/page/search-api-specs.md

@@ -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
 }
 ```