initial additional api definition

README.md

@@ -1,2 +1,196 @@
-# api
+## Дополнительный формат API (первичный черновик)
 
+Используемые коды:
+
+ - 200 - Выполнено успешно
+ - 201 - Заявка принята
+ - 403 - Доступ запрещен, не верный токен
+ - 502 - Внутрення ошибка (расшифровка в поле message в теле ответа)
+
+Используемые сущности
+ - matcher - (сборка) совокупность сайтов и исходных записей для сбора информации. Аналог группы.
+ - watchers - сайты, загруженные файлы поставщиков и/или конкурентов, метаформулы для вычисления результатов
+ - records - исходные данные для сбора информации
+ - rules - Правила сбора информации. Алиасы для брендов, логин пароль для авторизации на сайте и т.п
+
+### Создание сборки
+
+endpoint:  api/matcher/create?token=XXXXXXXXXXX
+
+REQUEST:
+
+```json
+
+{
+  "title": "Произвольное название сборки",
+  "watchers": [
+    {
+      "type" : "site",
+      "sld" : "emex.ru",
+      "city" : "москва",
+      "rules" : ["emex"]
+    }
+  ],
+  "records": [
+    {
+      "sku": "articul_code",
+      "vcode": "5531",
+      "brand": "ngk",
+      "title": "full item title",
+      "model": "5531",
+      "tags": [
+        "some",
+        "free",
+        "tags"
+      ],
+      "price": 5000
+    }
+  ]
+}
+```
+
+RESPONSE:  
+codes (200, 400, 403, 502)
+```json
+{
+  "code" : "http_code_duplicate",
+  "message" : "Описание ошибки если есть",
+  "matcher_id" : 10
+}
+```
+
+### Обновление исходных записей
+
+endpoint:  api/(matcher?|source?)/update&token=XXXXXXXXXXX   
+REQUEST
+```json
+
+{
+  "matcher_id": 10,
+  "matching": [
+    "brand",
+    "model"
+  ],
+  "actions": ["create", "update", "delete"],
+  "records": [
+    {
+      "sku": "articul_code",
+      "vcode": "5531",
+      "brand": "ngk",
+      "title": "full item title",
+      "model": "5531",
+      "tags": [
+        "some",
+        "free",
+        "tags"
+      ],
+      "price": 5000
+    }
+  ]
+}
+
+```
+
+### Запуск сбора данных
+
+endpoint api/matcher/start&token=XXXXXXXXXXX  
+REQUEST:
+
+```json
+{
+  "matcher_id": 10
+}
+```
+
+RESPONSE:  
+CODES: 201, 400, 403, 502
+
+```json
+{
+  "code": "http_code_duplicate",
+  "start_id": "идентификатор сбора данных",
+  "message": "Расшифровка ошибки если есть"
+}
+```
+
+### Остановка сбора данных
+
+endpoint api/matcher/stop&token=XXXXXXXXXXX   
+REQUEST:
+```json
+{
+  "matcher_id": 10
+}
+```
+RESPONSE:  
+CODES: 201, 400, 403, 502
+
+```json
+{
+  "message": ""
+}
+```
+
+### Состояние сборки 
+
+endpoint: api/matcher/status
+
+REQUEST:
+```json
+{
+  "matcher_id" : 10
+}
+```
+
+RESPONSE:
+
+```json
+{
+  "code": "http_code_duplicate",
+  "summary": "processing",
+  "watchers": [
+    {
+      "id": 11,
+      "title": "emex.ru",
+      "state": "processing",
+      "progress": 20,
+      "started_at": "2019-10-12T07:20:50.52Z"
+    },
+    {
+      "id": 12,
+      "title": "autopiter.ru",
+      "state": "idle",
+      "finished_at": "2019-10-12T07:20:50.52Z"
+    }
+  ]
+}
+```
+
+
+### Получение данных
+
+endpoint: api/matcher/export&token=XXXXXXXXXXX  
+REQUEST:
+
+```json
+{
+  "matcher_id": 10,
+  "format": "json|xlsx|csv",
+  "size": 100,   // размер страницы (0 - вернет все данные)
+  "page": 1      // Запрашиваемая страница
+}
+```
+
+RESPONSE:
+
+```json
+{
+  "page" : 1,       // Номер страницы с которой передаются данные
+  "pages": 10,      // ВСего страниц с данными
+  "next"  : 2,      // Номер следующей страницы
+  "is_last" : false // Последняя страница ?
+  "data" : [
+    ... данные в формате как в примере с учетом пожеланий по дате и кол-ву ...
+  ]
+}
+```