a/badguardhome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
117ec4dd43
badguardhome/openapi/CHANGELOG.md
Andrey Meshkov ceedc2d1ff *(querylog): added offset/limit parameters 
Actually, this is a serious refactoring of the query log module. The
rest API part is refactored, it's now more clear how the search is
conducted. Split the logic into more files and added more tests.

Closes: https://github.com/AdguardTeam/AdGuardHome/issues/1559
2020-05-26 15:37:37 +03:00

7.1 KiB
Raw Blame History

AdGuard Home API Change Log

v0.103: API changes

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