#18 WIP: start query API docs

TheHive-Project · Aug 31, 2021 · c5d0d3f · c5d0d3f
1 parent 5571f57
commit c5d0d3f
Show file tree

Hide file tree

Showing 6 changed files with 126 additions and 0 deletions.
diff --git a/docs/thehive/api/.pages b/docs/thehive/api/.pages
@@ -1,5 +1,6 @@
 nav:
   - index.md
+  - 'search'
   - 'organisation'
   - 'user'
   - 'custom-field'

diff --git a/docs/thehive/api/search/.pages b/docs/thehive/api/search/.pages
@@ -0,0 +1,5 @@
+nav:
+  - query.md
+  - filters.md
+  - sorting.md
+  - pagination.md
diff --git a/docs/thehive/api/search/filters.md b/docs/thehive/api/search/filters.md
diff --git a/docs/thehive/api/search/pagination.md b/docs/thehive/api/search/pagination.md
diff --git a/docs/thehive/api/search/query.md b/docs/thehive/api/search/query.md
@@ -0,0 +1,120 @@
+# Query API
+
+## Overview
+
+The Query API is the API used to search for objects with filtering and sorting capabilities. It's an API introduced by TheHive 4 and is optimized for the the new data model.
+
+TheHive comes with a list of predefined search *Queries* like:
+
+- `listOrganisation`
+- `listUser`
+- `listAlert`
+- `listCase`
+
+## Query
+
+```plain
+POST /api/v0/query
+```
+
+## Request Body
+
+The Query API request body should be an array of *operations* of different types:
+
+- Selection: *Required*
+    - list of objects
+    - object by identifier
+- Filtering: *optional*
+- Sorting: *optional*
+- Pagination: *optional*
+- Formatting: *optional*
+
+!!! Examples
+
+    === "Simple List"
+        ```json
+        {
+            "query": [
+                {
+                    "_name": "listOrganisation"
+                }
+            ]
+        }
+        ```
+    === "List with filters"
+        List organisations called *admin*
+        ```json
+        {
+            "query": [
+                {
+                    "_name": "listOrganisation"
+                },
+                {
+                    "_like": {
+                        "_field": "name",
+                        "_value": "admin"
+                    },
+                    "_name": "filter"
+                }
+            ]
+        }
+        ```
+    === "List with filters and sort"
+        List organisations called *admin*, sorted by ascendant `updatedAt` value
+        ```json
+        {
+            "query": [
+                {
+                    "_name": "listOrganisation"
+                },
+                {
+                    "_like": {
+                        "_field": "name",
+                        "_value": "admin"
+                    },
+                    "_name": "filter"
+                },
+                {
+                    "_fields": [
+                        {
+                            "updatedAt": "asc"
+                        }
+                    ],
+                    "_name": "sort"
+                }
+            ]
+        }
+        ```
+    === "List with pagination"
+        List organisations called *admin*, sorted by ascendant `updatedAt` value, paginated to display the first 15 items
+        ```json
+        {
+            "query": [
+                {
+                    "_name": "listOrganisation"
+                },
+                {
+                    "_like": {
+                        "_field": "name",
+                        "_value": "admin"
+                    },
+                    "_name": "filter"
+                },
+                {
+                    "_fields": [
+                        {
+                            "updatedAt": "asc"
+                        }
+                    ],
+                    "_name": "sort"
+                },
+                {
+                    "_name": "page",
+                    "from": 0,
+                    "to": 15
+                }
+            ]
+        }
+        ```
+
+
diff --git a/docs/thehive/api/search/sorting.md b/docs/thehive/api/search/sorting.md