a
/
badguardhome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
badguardhome/openapi.yaml

589 lines
20 KiB
YAML
Raw Normal View History

Initial commit
2018-08-30 14:25:33 +00:00
swagger: '2.0'
info:
Fix some UI issues, rename DNS->Home
2018-10-14 14:49:07 +00:00
title: 'AdGuard Home'
description: 'Control AdGuard Home server with this API'
Initial commit
2018-08-30 14:25:33 +00:00
version: 0.0.0
basePath: /control
schemes:
- http
produces:
- application/json
tags:
-
name: global
description: 'DNS server controls'
-
name: filtering
description: 'Rule-based filtering'
-
name: safebrowsing
description: 'Malware/hazardous sites'
-
name: parental
description: 'Sites inappropriate for children'
-
name: safesearch
description: 'Enforce family-friendly results in search engines'
paths:
/status:
get:
tags:
- global
operationId: status
summary: 'Get DNS server status'
responses:
200:
description: OK
Update /status to return currently set upstream DNS servers.
2018-09-25 16:53:15 +00:00
examples:
application/json:
dns_address: 127.0.0.1
dns_port: 53
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 17:13:03 +00:00
protection_enabled: true
Update /status to return currently set upstream DNS servers.
2018-09-25 16:53:15 +00:00
querylog_enabled: true
running: true
upstream_dns:
- 1.1.1.1
- 1.0.0.1
version: "v0.1"
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 17:13:03 +00:00
/enable_protection:
post:
tags:
-global
operationId: enableProtection
summary: "Enable protection (turns on dnsfilter module in coredns)"
responses:
200:
description: OK
/disable_protection:
post:
tags:
-global
operationId: disableProtection
summary: "Disable protection (turns off filtering, sb, parental, safesearch temporarily by disabling dnsfilter module in coredns)"
responses:
200:
description: OK
Initial commit
2018-08-30 14:25:33 +00:00
/querylog:
get:
tags:
- global
operationId: queryLog
summary: 'Get DNS server query log'
parameters:
- in: query
name: download
type: boolean
description: 'If any value is set, make the browser download the query instead of displaying it by setting Content-Disposition header'
responses:
200:
description: OK
examples:
application/json:
- answer:
- ttl: 55
type: A
value: 217.69.139.201
- ttl: 55
type: A
value: 94.100.180.200
- ttl: 55
type: A
value: 94.100.180.201
- ttl: 55
type: A
value: 217.69.139.200
elapsed_ms: '65.469556'
question:
class: IN
host: mail.ru
type: A
reason: DNSFILTER_NOTFILTERED_NOTFOUND
status: NOERROR
time: '2018-07-16T22:24:02+03:00'
- elapsed_ms: '0.15716999999999998'
question:
class: IN
host: doubleclick.net
type: A
reason: DNSFILTER_FILTERED_BLACKLIST
rule: "||doubleclick.net^"
status: NXDOMAIN
time: '2018-07-16T22:24:02+03:00'
- answer:
- ttl: 299
type: A
value: 176.103.133.78
elapsed_ms: '132.110929'
question:
class: IN
host: wmconvirus.narod.ru
type: A
reason: DNSFILTER_FILTERED_SAFEBROWSING
rule: adguard-malware-shavar
status: NOERROR
time: '2018-07-16T22:24:02+03:00'
/querylog_enable:
post:
tags:
- global
operationId: querylogEnable
summary: 'Enable querylog'
responses:
200:
description: OK
/querylog_disable:
post:
tags:
- global
operationId: querylogDisable
summary: 'Disable filtering'
responses:
200:
description: OK
/set_upstream_dns:
post:
tags:
- global
operationId: setUpstreamDNS
summary: 'Set upstream DNS for coredns, empty value will reset it to default values'
consumes:
- text/plain
parameters:
- in: body
name: upstream
description: 'Upstream servers, separated by newline or space, port is optional after colon'
schema:
type: string
example: |
1.1.1.1
1.0.0.1
8.8.8.8 8.8.4.4
192.168.1.104:53535
responses:
200:
description: OK
Implement API to test for upstream DNS servers.
2018-09-19 16:12:09 +00:00
/test_upstream_dns:
post:
tags:
- global
operationId: testUpstreamDNS
summary: 'Test upstream DNS'
consumes:
- text/plain
parameters:
- in: body
name: upstream
description: 'Upstream servers, separated by newline or space, port is optional after colon'
schema:
type: string
example: |
1.1.1.1
1.0.0.1
8.8.8.8 8.8.4.4
192.168.1.104:53535
responses:
200:
description: 'Status of testing each requested server, with "OK" meaning that server works, any other text means an error.'
examples:
application/json:
1.1.1.1: OK
1.0.0.1: OK
8.8.8.8: OK
8.8.4.4: OK
"192.168.1.104:53535": "Couldn't communicate with DNS server"
Initial commit
2018-08-30 14:25:33 +00:00
/stats_top:
get:
tags:
- global
operationId: statusTop
summary: 'Get DNS server top client, domain and blocked statistics'
responses:
200:
description: OK
examples:
application/json:
top_queried_domains:
example.org: 12312
example.com: 12312
example.net: 12312
example.ru: 12312
top_clients:
127.0.0.1: 12312
192.168.0.1: 13211
192.168.0.2: 13211
192.168.0.3: 13211
192.168.0.4: 13211
192.168.0.5: 13211
192.168.0.6: 13211
top_blocked_domains:
example.org: 12312
example.com: 12312
example.net: 12312
example.ru: 12312
/stats:
get:
tags:
- global
operationId: stats
summary: 'Get DNS server statistics'
responses:
200:
description: 'Gives statistics since start of the server'
examples:
application/json:
dns_queries: 1201
blocked_filtering: 123
replaced_safebrowsing: 5
replaced_parental: 18
replaced_safesearch: 94
avg_processing_time: 123
/stats_history:
get:
tags:
- global
operationId: stats_history
summary: 'Get historical DNS server statistics'
parameters:
-
name: start_time
in: query
type: string
description: 'Start time in ISO8601 (example: `2018-05-04T17:55:33+00:00`)'
required: true
-
name: end_time
in: query
type: string
description: 'End time in ISO8601 (example: `2018-05-04T17:55:33+00:00`)'
required: true
-
name: time_unit
in: query
type: string
description: 'Time unit (`minutes` or `hours`)'
required: true
enum:
- minutes
- hours
responses:
501:
description: 'Requested time window is outside of supported range. It will be supported later, but not now.'
200:
description: 'Gives statistics since start of the server. Example below is for 5 minutes. Values are from oldest to newest.'
examples:
application/json:
dns_queries:
- 1201
- 1201
- 1201
- 1201
- 1201
blocked_filtering:
- 123
- 123
- 123
- 123
- 123
replaced_safebrowsing:
- 5
- 5
- 5
- 5
- 5
replaced_parental:
- 18
- 18
- 18
- 18
- 18
replaced_safesearch:
- 94
- 94
- 94
- 94
- 94
avg_processing_time:
- 123
- 123
- 123
- 123
- 123
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 17:13:03 +00:00
/stats_reset:
post:
tags:
-global
operationId: statsReset
summary: "Reset all statistics to zeroes"
responses:
200:
description: OK
Initial commit
2018-08-30 14:25:33 +00:00
/filtering/enable:
post:
tags:
- filtering
operationId: filteringEnable
summary: 'Enable filtering'
responses:
200:
description: OK
/filtering/disable:
post:
tags:
- filtering
operationId: filteringDisable
summary: 'Disable filtering'
responses:
200:
description: OK
/filtering/add_url:
put:
tags:
- filtering
operationId: filteringAddURL
summary: 'Add filter URL'
consumes:
- text/plain
parameters:
- in: body
name: url
description: 'URL containing filtering rules'
required: true
schema:
type: string
example: 'url=https://filters.adtidy.org/windows/filters/15.txt'
responses:
200:
description: OK
/filtering/remove_url:
delete:
tags:
- filtering
operationId: filteringRemoveURL
summary: 'Remove filter URL'
consumes:
- text/plain
parameters:
- in: body
name: url
description: 'Previously added URL containing filtering rules'
required: true
schema:
type: string
example: 'url=https://filters.adtidy.org/windows/filters/15.txt'
responses:
200:
description: OK
/filtering/enable_url:
post:
tags:
- filtering
operationId: filteringEnableURL
summary: 'Enable filter URL'
consumes:
- text/plain
parameters:
- in: body
name: url
description: 'Previously added URL containing filtering rules'
required: true
schema:
type: string
example: 'url=https://filters.adtidy.org/windows/filters/15.txt'
responses:
200:
description: OK
/filtering/disable_url:
post:
tags:
- filtering
operationId: filteringDisableURL
summary: 'Disable filter URL'
consumes:
- text/plain
parameters:
- in: body
name: url
description: 'Previously added URL containing filtering rules'
required: true
schema:
type: string
example: 'url=https://filters.adtidy.org/windows/filters/15.txt'
responses:
200:
description: OK
/filtering/refresh:
post:
tags:
- filtering
operationId: filteringRefresh
summary: |
Reload filtering rules from URLs
This might be needed if new URL was just added and you dont want to wait for automatic refresh to kick in.
This API request is ratelimited, so you can call it freely as often as you like, it wont create unneccessary burden on servers that host the URL.
This should work as intended, a `force` parameter is offered as last-resort attempt to make filter lists fresh.
If you ever find yourself using `force` to make something work that otherwise wont, this is a bug and report it accordingly.
parameters:
-
name: force
in: query
type: boolean
description: 'If any value is set, ignore cache and force re-download of all filters'
responses:
200:
description: OK with how many filters were actually updated
/filtering/status:
get:
tags:
- filtering
operationId: filteringStatus
summary: 'Get status of rules-based filter'
responses:
200:
description: OK
examples:
application/json:
enabled: false
urls:
- 'https://filters.adtidy.org/windows/filters/1.txt'
- 'https://filters.adtidy.org/windows/filters/2.txt'
rules:
- '@@||yandex.ru^|'
/filtering/set_rules:
put:
tags:
- filtering
operationId: filteringSetRules
summary: 'Set user-defined filter rules'
consumes:
- text/plain
parameters:
- in: body
name: rules
description: 'All filtering rules, one line per rule'
schema:
type: string
example: '@@||yandex.ru^|'
responses:
200:
description: OK
/safebrowsing/enable:
post:
tags:
- safebrowsing
operationId: safebrowsingEnable
summary: 'Enable safebrowsing'
responses:
200:
description: OK
/safebrowsing/disable:
post:
tags:
- safebrowsing
operationId: safebrowsingDisable
summary: 'Disable safebrowsing'
responses:
200:
description: OK
/safebrowsing/status:
get:
tags:
- safebrowsing
operationId: safebrowsingStatus
summary: 'Get safebrowsing status'
responses:
200:
description: OK
examples:
application/json:
enabled: false
/parental/enable:
post:
tags:
- parental
operationId: parentalEnable
summary: 'Enable parental filtering'
consumes:
- text/plain
parameters:
- in: body
name: sensitivity
description: |
Age sensitivity for parental filtering,
EARLY_CHILDHOOD is 3
YOUNG is 10
TEEN is 13
MATURE is 17
required: true
schema:
type: string
enum:
- EARLY_CHILDHOOD
- YOUNG
- TEEN
- MATURE
example: 'sensitivity=TEEN'
responses:
200:
description: OK
/parental/disable:
post:
tags:
- parental
operationId: parentalDisable
summary: 'Disable parental filtering'
responses:
200:
description: OK
/parental/status:
get:
tags:
- parental
operationId: parentalStatus
summary: 'Get parental filtering status'
responses:
200:
description: OK
examples:
application/json:
enabled: true
sensitivity: 13
/safesearch/enable:
post:
tags:
- safesearch
operationId: safesearchEnable
summary: 'Enable safesearch'
responses:
200:
description: OK
/safesearch/disable:
post:
tags:
- safesearch
operationId: safesearchDisable
summary: 'Disable safesearch'
responses:
200:
description: OK
/safesearch/status:
get:
tags:
- safesearch
operationId: safesearchStatus
summary: 'Get safesearch status'
responses:
200:
description: OK
examples:
application/json:
enabled: false
definitions:
rule:
type: string