From ff1c8fd8e9c42a0745da89c0a72e9828fcc84848 Mon Sep 17 00:00:00 2001
From: Alexey Kasyanchuk <degitx@gmail.com>
Date: Tue, 6 Jun 2023 16:43:58 +0300
Subject: [PATCH] Added API documentation (basic)

---
 README.md   |  4 ++-
 docs/API.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 docs/API.md

diff --git a/README.md b/README.md
index 5bb7090..354c73e 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ BitTorrent search program for desktop and web. Collect and navigate over base of
 * Drag and drop torrents (expand local search database with specific torrents)
 * Descriptions association from trackers
 * Torrent generation and automatic adding to search DB
-* WebSockets & REST API for server/search engine. You can made search request and create your own UI client.
+* [WebSockets & REST API for server/search engine. You can made search request and create your own UI client.](docs/API.md)
 
 ## Architecture
 ![Basic Architecture](docs/img/ratsarch.png)
@@ -92,6 +92,8 @@ Now you can get access to web interface on 8095 port: http://localhost:8095
 
 [More about server compatibility and known issues](docs/SERVER_COMPATIBILITY.md)
 
+[API usage implementation for clients](docs/API.md)
+
 ## Docker image
 
 You can simply run docker image with prepared server version. Just download last sources:
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..e4adfcd
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,73 @@
+# Basic description
+
+Rats Search server using WebSockets for internal communication. It require two way communication and using socket.io internally. As alternative added REST API implementation, but because of one-way limitation, it require periodic check of backward messages with **/api/queue** . You free to choise one of the ways for communication and implementation of your own client.
+
+## WebSockets communication (1-way)
+
+
+## REST API communication (2-way)
+
+### Installation
+
+At first you need to prepare server non-interface version
+
+```bash
+git clone --recurse-submodules https://github.com/DEgITx/rats-search.git
+npm install --force
+npm run buildweb
+npm run server
+```
+
+### Configuration
+
+You need to enable REST API configuration (disabled by default):
+
+edit **rats.json** (change only restApi value):
+```json
+{
+    "restApi": true
+}
+```
+
+set restApi to true, save
+
+### API usage
+
+#### Search of torrents
+
+endpoint (GET REQUEST):
+```
+https://localhost:8095/api/searchTorrent?text=DEgITx&navigation={}
+```
+
+example of request:
+```json
+{
+    "text": "Search Name of the torrent",
+    "navigation": {
+        "index": 0,
+        "limit": 10,
+        "orderBy": "order_field",
+        "orderDesc": "DESC"
+    }
+}
+```
+
+fields:
+* text (string) - torrent search name
+* navigation (object) [optional] - object with navigation params
+* * index (int) [optional] - stating of torrent index of navigation
+* * limit (int) [optional] [default: 10] - max number of results on page
+* * orderBy (text) [optional] - field which is using for order results
+* * orderDesc (enum [DESC, ASC]) [optional] - sort direction of the field
+
+#### Reading queue
+
+As said before after each request and periodicly you need to read queue for additional messaged
+
+endpoint (GET REQUEST):
+```
+https://localhost:8095/api/queue
+```
+
+after executing of search **/api/searchTorrent** request **additional result of search will be in queue**!
\ No newline at end of file