AdguardTeam/AdGuardHome
1
1
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2024-12-15 19:31:45 +03:00
Code Issues Packages Projects Releases Wiki Activity
8aad02dbf2
AdGuardHome/openapi/CHANGELOG.md
Simon Zolin e2ddc82d70 + DNS: add fastest_addr setting 
* API: /dns_info, /dns_config: add "parallel_requests" instead of "all_servers" from /set_upstreams_config
* API: /status: removed fields

#715

Squashed commit of the following:

commit 7dd913bd336ecbaa7419b998d0bf913d89702fe6
Merge: 43706970 8170955a
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Wed Apr 22 19:09:36 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit 437069702a3e91e0b066e4b22b08cdc02ff19eaf
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Wed Apr 22 19:08:55 2020 +0300

    minor

commit 9e713df80c5bf113c98794c0a20915c756a76938
Merge: e3bf4037 9b7c1181
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Tue Apr 21 16:02:03 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit e3bf4037f49198e42bde55305d6f9077341b556a
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Tue Apr 21 15:40:49 2020 +0300

    minor

commit d6e6a823c5e51acc061b2850d362772efcb827e1
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Apr 17 17:56:24 2020 +0300

    * API changes

    . removed POST /set_upstreams_config
    . removed fields from GET /status: bootstrap_dns, upstream_dns, all_servers
    . added new fields to /dns_config and /dns_info

commit 237a452d09cc48ff8f00e81c7fd35e7828bea835
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Apr 17 16:43:13 2020 +0300

    * API: /dns_info, /dns_config: add "parallel_requests" instead of "all_servers" from /set_upstreams_config

commit 9976723b9725ed19e0cce152d1d1198b13c4acc1
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Mon Mar 23 10:28:25 2020 +0300

    openapi

commit 6f8ea16c6332606f29095b0094d71e8a91798f82
Merge: 36e4d4e8 c8285c41
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Mar 20 19:18:48 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit 36e4d4e82cadeaba5a11313f0d69d66a0924c342
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Mar 20 18:13:43 2020 +0300

    + DNS: add fastest_addr setting
2020-04-22 19:14:04 +03:00

6.8 KiB
Raw Blame History

AdGuard Home API Change Log

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},
		...
	]
}