From 1fc70cbc08736d71c19dab8fb713c9b016314fdb Mon Sep 17 00:00:00 2001
From: Simon Zolin <s.zolin@adguard.com>
Date: Tue, 19 Nov 2019 19:34:07 +0300
Subject: [PATCH] * openapi: update 'Client' object; add /clients/find

---
 openapi/CHANGELOG.md | 89 ++++++++++++++++++++++++++++++++++++++++++++
 openapi/openapi.yaml | 41 +++++++++++++++++---
 2 files changed, 124 insertions(+), 6 deletions(-)

diff --git a/openapi/CHANGELOG.md b/openapi/CHANGELOG.md
index 3172be07..c6e79b8a 100644
--- a/openapi/CHANGELOG.md
+++ b/openapi/CHANGELOG.md
@@ -1,6 +1,95 @@
 # AdGuard Home API Change Log
 
 
+## v0.100: API changes
+
+### API: Get list of clients: GET /control/clients
+
+* "ip" and "mac" fields are removed
+* "ids" and "ip_addrs" fields are added
+
+Response:
+
+	200 OK
+
+	{
+	clients: [
+		{
+			name: "client1"
+			ids: ["...", ...] // IP or MAC
+			ip_addrs: ["...", ...] // all IP addresses (set by user and resolved by MAC)
+			use_global_settings: true
+			filtering_enabled: false
+			parental_enabled: false
+			safebrowsing_enabled: false
+			safesearch_enabled: false
+			use_global_blocked_services: true
+			blocked_services: [ "name1", ... ]
+			whois_info: {
+				key: "value"
+				...
+			}
+		}
+	]
+	auto_clients: [
+		{
+			name: "host"
+			ip: "..."
+			source: "etc/hosts" || "rDNS"
+			whois_info: {
+				key: "value"
+				...
+			}
+		}
+	]
+	}
+
+### API: Add client: POST /control/clients/add
+
+* "ip" and "mac" fields are removed
+* "ids" field is added
+
+Request:
+
+	POST /control/clients/add
+
+	{
+		name: "client1"
+		ids: ["...", ...] // IP or MAC
+		use_global_settings: true
+		filtering_enabled: false
+		parental_enabled: false
+		safebrowsing_enabled: false
+		safesearch_enabled: false
+		use_global_blocked_services: true
+		blocked_services: [ "name1", ... ]
+	}
+
+### API: Update client: POST /control/clients/update
+
+* "ip" and "mac" fields are removed
+* "ids" field is added
+
+Request:
+
+	POST /control/clients/update
+
+	{
+		name: "client1"
+		data: {
+			name: "client1"
+			ids: ["...", ...] // IP or MAC
+			use_global_settings: true
+			filtering_enabled: false
+			parental_enabled: false
+			safebrowsing_enabled: false
+			safesearch_enabled: false
+			use_global_blocked_services: true
+			blocked_services: [ "name1", ... ]
+		}
+	}
+
+
 ## v0.99.3: API changes
 
 ### API: Get query log: GET /control/querylog
diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml
index 406194b2..6514922c 100644
--- a/openapi/openapi.yaml
+++ b/openapi/openapi.yaml
@@ -772,6 +772,22 @@ paths:
                 200:
                     description: OK
 
+    /clients/find:
+        get:
+            tags:
+                - clients
+            operationId: clientsFind
+            summary: 'Get information about selected clients by their IP address'
+            parameters:
+                - name: ip0
+                  in: query
+                  type: string
+            responses:
+                200:
+                    description: OK
+                    schema:
+                        $ref: "#/definitions/ClientsFindResponse"
+
 
     /blocked_services/list:
         get:
@@ -1589,16 +1605,15 @@ definitions:
         type: "object"
         description: "Client information"
         properties:
-            ip:
-                type: "string"
-                description: "IP address"
-                example: "127.0.0.1"
             name:
                 type: "string"
                 description: "Name"
                 example: "localhost"
-            mac:
-                type: "string"
+            ids:
+                type: "array"
+                description: "IP, CIDR or MAC address"
+                items:
+                    type: "string"
             use_global_settings:
                 type: "boolean"
             filtering_enabled:
@@ -1645,6 +1660,20 @@ definitions:
         properties:
             name:
                 type: "string"
+
+    ClientsFindResponse:
+        type: "array"
+        description: "Response to clients find operation"
+        items:
+            $ref: "#/definitions/ClientsFindEntry"
+
+    ClientsFindEntry:
+        type: "object"
+        properties:
+            "1.2.3.4":
+                items:
+                    $ref: "#/definitions/Client"
+
     Clients:
         type: "object"
         properties: