2e8352d31c
Merge in DNS/adguard-home from 2102-rules-result to master Updates #2102. Squashed commit of the following: commit 47b2aa94c56b37be492c3c01e8111054612d9722 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 17 13:12:27 2020 +0300 querylog: remove pre-v0.99.3 compatibility code commit 2af0ee43c2444a7d842fcff057f2ba02f300244b Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 17 13:00:27 2020 +0300 all: improve documentation commit 3add300a42f0aa67bb315a448e294636c85d0b3b Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 16 18:30:01 2020 +0300 all: improve changelog commit e04ef701fc2de7f4453729e617641c47e0883679 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 16 17:56:53 2020 +0300 all: improve code and documentation commit 4f04845ae275ae4291869e00c62e4ff81b01eaa3 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 16 17:01:08 2020 +0300 all: document changes, improve api commit bc59b7656a402d0c65f13bd74a71d8dda6a8a65d Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 15 18:22:01 2020 +0300 all: allow multiple rules in dns filter results
437 lines
8.1 KiB
Markdown
437 lines
8.1 KiB
Markdown
# AdGuard Home API Change Log
|
|
|
|
<!-- TODO(a.garipov): Reformat in accordance with the KeepAChangelog spec. -->
|
|
|
|
## v0.105: API changes
|
|
|
|
### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog`
|
|
|
|
<!-- TODO(a.garipov): Update with better examples once $dnsrewrite rules are
|
|
checked in. -->
|
|
|
|
* The properties `rule` and `filter_id` are now deprecated. API users should
|
|
inspect the newly-added `rules` object array instead. Currently, it's either
|
|
empty or contains one object, which contains the same things as the old two
|
|
properties did, but under more correct names:
|
|
|
|
```js
|
|
{
|
|
// …
|
|
|
|
// Deprecated.
|
|
"rule": "||example.com^",
|
|
// Deprecated.
|
|
"filter_id": 42,
|
|
// Newly-added.
|
|
"rules": [{
|
|
"text": "||example.com^",
|
|
"filter_list_id": 42
|
|
}]
|
|
}
|
|
```
|
|
|
|
The old fields will be removed in v0.106.0.
|
|
|
|
## v0.103: API changes
|
|
|
|
### API: replace settings in GET /control/dns_info & POST /control/dns_config
|
|
|
|
* added "upstream_mode"
|
|
|
|
"upstream_mode": "" | "parallel" | "fastest_addr"
|
|
|
|
* removed "fastest_addr", "parallel_requests"
|
|
|
|
|
|
### API: Get querylog: GET /control/querylog
|
|
|
|
* Added optional "offset" and "limit" parameters
|
|
|
|
We are still using "older_than" approach in AdGuard Home UI, but we realize that it's easier to use offset/limit so here is this option now.
|
|
|
|
|
|
## v0.102: API changes
|
|
|
|
### API: Get general status: GET /control/status
|
|
|
|
* Removed "upstream_dns", "bootstrap_dns", "all_servers" parameters
|
|
|
|
### API: Get DNS general settings: GET /control/dns_info
|
|
|
|
* Added "parallel_requests", "upstream_dns", "bootstrap_dns" parameters
|
|
|
|
Request:
|
|
|
|
GET /control/dns_info
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
{
|
|
"upstream_dns": ["tls://...", ...],
|
|
"bootstrap_dns": ["1.2.3.4", ...],
|
|
|
|
"protection_enabled": true | false,
|
|
"ratelimit": 1234,
|
|
"blocking_mode": "default" | "nxdomain" | "null_ip" | "custom_ip",
|
|
"blocking_ipv4": "1.2.3.4",
|
|
"blocking_ipv6": "1:2:3::4",
|
|
"edns_cs_enabled": true | false,
|
|
"dnssec_enabled": true | false
|
|
"disable_ipv6": true | false,
|
|
"fastest_addr": true | false, // use Fastest Address algorithm
|
|
"parallel_requests": true | false, // send DNS requests to all upstream servers at once
|
|
}
|
|
|
|
### API: Set DNS general settings: POST /control/dns_config
|
|
|
|
* Added "parallel_requests", "upstream_dns", "bootstrap_dns" parameters
|
|
* removed /control/set_upstreams_config method
|
|
|
|
Request:
|
|
|
|
POST /control/dns_config
|
|
|
|
{
|
|
"upstream_dns": ["tls://...", ...],
|
|
"bootstrap_dns": ["1.2.3.4", ...],
|
|
|
|
"protection_enabled": true | false,
|
|
"ratelimit": 1234,
|
|
"blocking_mode": "default" | "nxdomain" | "null_ip" | "custom_ip",
|
|
"blocking_ipv4": "1.2.3.4",
|
|
"blocking_ipv6": "1:2:3::4",
|
|
"edns_cs_enabled": true | false,
|
|
"dnssec_enabled": true | false
|
|
"disable_ipv6": true | false,
|
|
"fastest_addr": true | false, // use Fastest Address algorithm
|
|
"parallel_requests": true | false, // send DNS requests to all upstream servers at once
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
|
|
## v0.101: API changes
|
|
|
|
### API: Refresh filters: POST /control/filtering/refresh
|
|
|
|
* Added "whitelist" boolean parameter
|
|
* Response is in JSON format
|
|
|
|
Request:
|
|
|
|
POST /control/filtering/refresh
|
|
|
|
{
|
|
"whitelist": true
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
{
|
|
"updated": 123 // number of filters updated
|
|
}
|
|
|
|
|
|
## 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
|
|
|
|
The response data is now a JSON object, not an array.
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
{
|
|
"oldest":"2006-01-02T15:04:05.999999999Z07:00"
|
|
"data":[
|
|
{
|
|
"answer":[
|
|
{
|
|
"ttl":10,
|
|
"type":"AAAA",
|
|
"value":"::"
|
|
}
|
|
...
|
|
],
|
|
"client":"127.0.0.1",
|
|
"elapsedMs":"0.098403",
|
|
"filterId":1,
|
|
"question":{
|
|
"class":"IN",
|
|
"host":"doubleclick.net",
|
|
"type":"AAAA"
|
|
},
|
|
"reason":"FilteredBlackList",
|
|
"rule":"||doubleclick.net^",
|
|
"status":"NOERROR",
|
|
"time":"2006-01-02T15:04:05.999999999Z07:00"
|
|
}
|
|
...
|
|
]
|
|
}
|
|
|
|
|
|
## v0.99.1: API changes
|
|
|
|
### API: Get current user info: GET /control/profile
|
|
|
|
Request:
|
|
|
|
GET /control/profile
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
{
|
|
"name":"..."
|
|
}
|
|
|
|
|
|
### Set DNS general settings: POST /control/dns_config
|
|
|
|
Replaces these API methods:
|
|
|
|
POST /control/enable_protection
|
|
POST /control/disable_protection
|
|
|
|
Request:
|
|
|
|
POST /control/dns_config
|
|
|
|
{
|
|
"protection_enabled": true | false,
|
|
"ratelimit": 1234,
|
|
"blocking_mode": "nxdomain" | "null_ip" | "custom_ip",
|
|
"blocking_ipv4": "1.2.3.4",
|
|
"blocking_ipv6": "1:2:3::4",
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
|
|
## v0.99: incompatible API changes
|
|
|
|
* A note about web user authentication
|
|
* Set filtering parameters: POST /control/filtering/config
|
|
* Set filter parameters: POST /control/filtering/set_url
|
|
* Set querylog parameters: POST /control/querylog_config
|
|
* Get statistics data: GET /control/stats
|
|
|
|
|
|
### A note about web user authentication
|
|
|
|
If AdGuard Home's web user is password-protected, a web client must use authentication mechanism when sending requests to server. Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
|
|
|
|
Authorization: Basic BASE64_DATA
|
|
|
|
where BASE64_DATA is base64-encoded data for `username:password` string.
|
|
|
|
|
|
### Set filtering parameters: POST /control/filtering/config
|
|
|
|
Replaces these API methods:
|
|
|
|
POST /control/filtering/enable
|
|
POST /control/filtering/disable
|
|
|
|
Request:
|
|
|
|
POST /control/filtering_config
|
|
|
|
{
|
|
"enabled": true | false
|
|
"interval": 0 | 1 | 12 | 1*24 | 3*24 | 7*24
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
|
|
### Set filter parameters: POST /control/filtering/set_url
|
|
|
|
Replaces these API methods:
|
|
|
|
POST /control/filtering/enable_url
|
|
POST /control/filtering/disable_url
|
|
|
|
Request:
|
|
|
|
POST /control/filtering/set_url
|
|
|
|
{
|
|
"url": "..."
|
|
"enabled": true | false
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
|
|
### Set querylog parameters: POST /control/querylog_config
|
|
|
|
Replaces these API methods:
|
|
|
|
POST /querylog_enable
|
|
POST /querylog_disable
|
|
|
|
Request:
|
|
|
|
POST /control/querylog_config
|
|
|
|
{
|
|
"enabled": true | false
|
|
"interval": 1 | 7 | 30 | 90
|
|
}
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
|
|
### Get statistics data: GET /control/stats
|
|
|
|
Replaces these API methods:
|
|
|
|
GET /control/stats_top
|
|
GET /control/stats_history
|
|
|
|
Request:
|
|
|
|
GET /control/stats
|
|
|
|
Response:
|
|
|
|
200 OK
|
|
|
|
{
|
|
time_units: hours | days
|
|
|
|
// total counters:
|
|
num_dns_queries: 123
|
|
num_blocked_filtering: 123
|
|
num_replaced_safebrowsing: 123
|
|
num_replaced_safesearch: 123
|
|
num_replaced_parental: 123
|
|
avg_processing_time: 123.123
|
|
|
|
// per time unit counters
|
|
dns_queries: [123, ...]
|
|
blocked_filtering: [123, ...]
|
|
replaced_parental: [123, ...]
|
|
replaced_safebrowsing: [123, ...]
|
|
|
|
top_queried_domains: [
|
|
{host: 123},
|
|
...
|
|
]
|
|
top_blocked_domains: [
|
|
{host: 123},
|
|
...
|
|
]
|
|
top_clients: [
|
|
{IP: 123},
|
|
...
|
|
]
|
|
}
|