cotugno/AdGuardHome
2
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2024-11-17 02:48:28 -07:00
Code Issues Packages Projects Releases Wiki Activity
1448b7ab16
AdGuardHome/openapi/openapi.yaml

1371 lines
44 KiB
YAML
Raw Normal View History

Initial commit
2018-08-30 07:25:33 -07:00
swagger: '2.0'
info:
Fix some UI issues, rename DNS->Home
2018-10-14 07:49:07 -07:00
title: 'AdGuard Home'
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
description: 'AdGuard Home REST API. Admin web interface is built on top of this REST API.'
Added openapi description
2019-02-21 07:33:46 -07:00
version: 0.93.0
Initial commit
2018-08-30 07:25:33 -07:00
schemes:
- http
Added version.json
2018-11-26 03:22:14 -07:00
basePath: /control
Initial commit
2018-08-30 07:25:33 -07:00
produces:
- application/json
tags:
-
name: global
Added more definitions
2018-11-25 12:30:08 -07:00
description: 'AdGuard Home server general settings and controls'
Added openapi description
2019-02-21 07:33:46 -07:00
-
name: tls
description: 'AdGuard Home HTTPS/DOH/DOT settings'
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
-
name: log
description: 'AdGuard Home query log'
Added more definitions
2018-11-25 12:30:08 -07:00
-
name: stats
description: 'AdGuard Home statistics'
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
-
name: i18n
description: 'Application localization'
Initial commit
2018-08-30 07:25:33 -07:00
-
name: filtering
description: 'Rule-based filtering'
-
name: safebrowsing
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
description: 'Blocking malware/phishing sites'
Initial commit
2018-08-30 07:25:33 -07:00
-
name: parental
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
description: 'Blocking adult and explicit materials'
Initial commit
2018-08-30 07:25:33 -07:00
-
name: safesearch
description: 'Enforce family-friendly results in search engines'
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
-
name: dhcp
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
description: 'Built-in DHCP server controls'
+ control: /clients: get the list of clients' IP addresses and names from /etc/hosts
2019-03-19 08:47:22 -07:00
-
name: clients
description: 'Clients list operations'
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
-
name: install
description: 'First-time install configuration handlers'
Initial commit
2018-08-30 07:25:33 -07:00
paths:
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# API TO-DO LIST
# TODO: Use JSON where it is possible
# TODO: Use lower_case for all objects' properties
# TODO: Move to definitions what's missing from there
# --------------------------------------------------
# General settings and controls
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/status:
get:
tags:
- global
operationId: status
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
summary: 'Get DNS server current status and general settings'
Added more definitions
2018-11-25 12:30:08 -07:00
produces:
- application/json
Initial commit
2018-08-30 07:25:33 -07:00
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
schema:
$ref: "#/definitions/ServerStatus"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
/enable_protection:
post:
tags:
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
- global
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
operationId: enableProtection
summary: "Enable protection (turns on dnsfilter module in coredns)"
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
/disable_protection:
post:
tags:
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
- global
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
operationId: disableProtection
summary: "Disable protection (turns off filtering, sb, parental, safesearch temporarily by disabling dnsfilter module in coredns)"
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Add set_upstreams_config function
2019-02-28 01:10:43 -07:00
/set_upstreams_config:
post:
tags:
- global
operationId: setUpstreamsConfig
summary: "Updates the current upstreams configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "Upstreams configuration JSON"
required: true
schema:
$ref: "#/definitions/UpstreamsConfig"
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
/test_upstream_dns:
post:
tags:
- global
operationId: testUpstreamDNS
[change] config, control, openapi: fix issues from reviw
2019-03-06 06:17:15 -07:00
summary: "Test upstream configuration"
Added more definitions
2018-11-25 12:30:08 -07:00
consumes:
[change] control, openapi: Handle upstreams test with JSON
2019-03-05 02:29:52 -07:00
- application/json
Added more definitions
2018-11-25 12:30:08 -07:00
parameters:
[change] control, openapi: Handle upstreams test with JSON
2019-03-05 02:29:52 -07:00
- in: "body"
name: "body"
[change] config, control, openapi: fix issues from reviw
2019-03-06 06:17:15 -07:00
description: "Upstream configuration to be tested"
Added more definitions
2018-11-25 12:30:08 -07:00
schema:
[change] config, control, openapi: fix issues from reviw
2019-03-06 06:17:15 -07:00
$ref: "#/definitions/UpstreamsConfig"
Added more definitions
2018-11-25 12:30:08 -07:00
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"
Added version.json
2018-11-26 03:22:14 -07:00
/version.json:
get:
tags:
- global
operationId: getVersionJson
summary: 'Gets information about the latest available version of AdGuard'
produces:
- 'application/json'
responses:
200:
description: 'Version info'
schema:
$ref: "#/definitions/VersionInfo"
500:
description: 'Cannot write answer'
502:
description: 'Cannot retrieve the version.json file contents'
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# Query log methods
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/querylog:
get:
tags:
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
- log
Initial commit
2018-08-30 07:25:33 -07:00
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
Added more openapi definitions
2018-11-25 14:08:47 -07:00
schema:
$ref: '#/definitions/QueryLog'
Initial commit
2018-08-30 07:25:33 -07:00
/querylog_enable:
post:
tags:
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
- log
Initial commit
2018-08-30 07:25:33 -07:00
operationId: querylogEnable
summary: 'Enable querylog'
responses:
200:
description: OK
/querylog_disable:
post:
tags:
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
- log
Initial commit
2018-08-30 07:25:33 -07:00
operationId: querylogDisable
summary: 'Disable filtering'
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# General statistics methods
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/stats_top:
get:
tags:
Added more definitions
2018-11-25 12:30:08 -07:00
- stats
Initial commit
2018-08-30 07:25:33 -07:00
operationId: statusTop
summary: 'Get DNS server top client, domain and blocked statistics'
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
schema:
$ref: "#/definitions/StatsTop"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/stats:
get:
tags:
Added more definitions
2018-11-25 12:30:08 -07:00
- stats
Initial commit
2018-08-30 07:25:33 -07:00
operationId: stats
summary: 'Get DNS server statistics'
responses:
200:
Added more openapi definitions
2018-11-25 14:08:47 -07:00
description: 'Returns general statistics for the last 24 hours'
schema:
$ref: "#/definitions/Stats"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/stats_history:
get:
tags:
Added more definitions
2018-11-25 12:30:08 -07:00
- stats
Initial commit
2018-08-30 07:25:33 -07:00
operationId: stats_history
Added more openapi definitions
2018-11-25 14:08:47 -07:00
summary: 'Get historical DNS server statistics for the last 24 hours'
Initial commit
2018-08-30 07:25:33 -07:00
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:
Added more openapi definitions
2018-11-25 14:08:47 -07:00
description: 'Returns historical stats for the specified time interval.'
schema:
$ref: '#/definitions/StatsHistory'
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
/stats_reset:
post:
tags:
Added more definitions
2018-11-25 12:30:08 -07:00
- stats
API backend -- implement ability to turn toggle all protection in one go, helpful to temporarily disable all kinds of filtering
2018-10-10 10:13:03 -07:00
operationId: statsReset
summary: "Reset all statistics to zeroes"
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
Added openapi description
2019-02-21 07:33:46 -07:00
# --------------------------------------------------
# TLS server methods
# --------------------------------------------------
/tls/status:
get:
tags:
- tls
operationId: tlsStatus
summary: "Returns TLS configuration and its status"
responses:
200:
description: OK
schema:
$ref: "#/definitions/TlsConfig"
/tls/configure:
post:
tags:
- tls
operationId: tlsConfigure
summary: "Updates current TLS configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "TLS configuration JSON"
required: true
schema:
$ref: "#/definitions/TlsConfig"
responses:
200:
description: "TLS configuration and its status"
schema:
$ref: "#/definitions/TlsConfig"
400:
description: "Invalid configuration or unavailable port"
500:
description: "Error occurred while applying configuration"
/tls/validate:
post:
tags:
- tls
operationId: tlsValidate
summary: "Checks if the current TLS configuration is valid"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "TLS configuration JSON"
required: true
schema:
$ref: "#/definitions/TlsConfig"
responses:
200:
description: "TLS configuration and its status"
schema:
$ref: "#/definitions/TlsConfig"
400:
description: "Invalid configuration or unavailable port"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# DHCP server methods
# --------------------------------------------------
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
/dhcp/status:
Added more definitions
2018-11-25 12:30:08 -07:00
get:
tags:
- dhcp
operationId: dhcpStatus
summary: "Gets the current DHCP settings and status"
responses:
200:
description: OK
schema:
$ref: "#/definitions/DhcpStatus"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
/dhcp/set_config:
Added more definitions
2018-11-25 12:30:08 -07:00
post:
tags:
- dhcp
operationId: dhcpSetConfig
summary: "Updates the current DHCP server configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "DHCP configuration JSON"
required: true
schema:
$ref: "#/definitions/DhcpConfig"
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
/dhcp/find_active_dhcp:
Send dhcp/find_active_dhcp as POST request
2018-12-13 04:39:59 -07:00
post:
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
tags:
Added swagger UI scripts
2018-11-25 10:09:52 -07:00
- dhcp
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
operationId: checkActiveDhcp
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
summary: "Searches for an active DHCP server on the network"
Add dhcp methods to the openapi.yaml
2018-11-06 02:22:44 -07:00
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
schema:
$ref: "#/definitions/DhcpSearchResult"
# --------------------------------------------------
# Filtering status methods
# --------------------------------------------------
/filtering/status:
get:
tags:
- filtering
operationId: filteringStatus
summary: 'Get status of rules-based filter'
responses:
200:
description: OK
schema:
$ref: "#/definitions/FilteringStatus"
Added more definitions
2018-11-25 12:30:08 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/filtering/enable:
post:
tags:
- filtering
operationId: filteringEnable
summary: 'Enable filtering'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/filtering/disable:
post:
tags:
- filtering
operationId: filteringDisable
summary: 'Disable filtering'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/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:
Added more definitions
2018-11-25 12:30:08 -07:00
# TODO: move to definitions
Initial commit
2018-08-30 07:25:33 -07:00
type: string
example: '@@||yandex.ru^|'
responses:
200:
description: OK
Added more definitions
2018-11-25 12:30:08 -07:00
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# Safebrowsing methods
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/safebrowsing/enable:
post:
tags:
- safebrowsing
operationId: safebrowsingEnable
summary: 'Enable safebrowsing'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/safebrowsing/disable:
post:
tags:
- safebrowsing
operationId: safebrowsingDisable
summary: 'Disable safebrowsing'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/safebrowsing/status:
get:
tags:
- safebrowsing
operationId: safebrowsingStatus
summary: 'Get safebrowsing status'
responses:
200:
description: OK
examples:
application/json:
enabled: false
Added more definitions
2018-11-25 12:30:08 -07:00
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# Parental control methods
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/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
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/parental/disable:
post:
tags:
- parental
operationId: parentalDisable
summary: 'Disable parental filtering'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/parental/status:
get:
tags:
- parental
operationId: parentalStatus
summary: 'Get parental filtering status'
responses:
200:
description: OK
examples:
application/json:
enabled: true
sensitivity: 13
Added more definitions
2018-11-25 12:30:08 -07:00
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# Safe search methods
# --------------------------------------------------
Initial commit
2018-08-30 07:25:33 -07:00
/safesearch/enable:
post:
tags:
- safesearch
operationId: safesearchEnable
summary: 'Enable safesearch'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/safesearch/disable:
post:
tags:
- safesearch
operationId: safesearchDisable
summary: 'Disable safesearch'
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Initial commit
2018-08-30 07:25:33 -07:00
/safesearch/status:
get:
tags:
- safesearch
operationId: safesearchStatus
summary: 'Get safesearch status'
responses:
200:
description: OK
examples:
application/json:
enabled: false
Added more definitions
2018-11-25 12:30:08 -07:00
+ control: /clients: get the list of clients' IP addresses and names from /etc/hosts
2019-03-19 08:47:22 -07:00
# --------------------------------------------------
# Clients list methods
# --------------------------------------------------
/clients:
get:
tags:
- clients
operationId: clientsStatus
summary: 'Get information about configured clients'
responses:
200:
description: OK
schema:
$ref: "#/definitions/Clients"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
# --------------------------------------------------
# I18N methods
# --------------------------------------------------
Added more definitions
2018-11-25 12:30:08 -07:00
/i18n/change_language:
post:
tags:
- i18n
operationId: changeLanguage
summary: "Change current language. Argument must be an ISO 639-1 two-letter code"
consumes:
- text/plain
parameters:
- in: body
name: language
description: "New language. It must be known to the server and must be an ISO 639-1 two-letter code"
schema:
# TODO: use JSON?
type: string
example: en
responses:
200:
description: OK
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Added more definitions
2018-11-25 12:30:08 -07:00
/i18n/current_language:
get:
tags:
- i18n
operationId: currentLanguage
summary: "Get currently set language. Result is ISO 639-1 two-letter code. Empty result means default language."
responses:
200:
description: OK
examples:
text/plain:
en
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
# --------------------------------------------------
# First-time install configuration methods
# --------------------------------------------------
/install/get_addresses:
get:
tags:
- install
operationId: installGetAddresses
summary: "Gets the network interfaces information."
responses:
200:
description: OK
schema:
$ref: "#/definitions/AddressesInfo"
/install/configure:
post:
tags:
- install
operationId: installConfigure
summary: "Applies the initial configuration."
parameters:
- in: "body"
name: "body"
description: "Initial configuration JSON"
required: true
schema:
$ref: "#/definitions/InitialConfiguration"
responses:
200:
description: OK
400:
description: "Failed to parse initial configuration or cannot listen to the specified addresses"
500:
description: "Cannot start the DNS server"
Initial commit
2018-08-30 07:25:33 -07:00
definitions:
Added more definitions
2018-11-25 12:30:08 -07:00
ServerStatus:
type: "object"
description: "AdGuard Home server status and configuration"
required:
- "dns_address"
- "dns_port"
- "protection_enabled"
- "querylog_enabled"
- "running"
- "bootstrap_dns"
- "upstream_dns"
- "version"
- "language"
properties:
dns_address:
type: "string"
example: "127.0.0.1"
dns_port:
type: "integer"
format: "int32"
example: 53
minimum: 1
maximum: 65535
protection_enabled:
type: "boolean"
querylog_enabled:
type: "boolean"
running:
type: "boolean"
bootstrap_dns:
type: "string"
example: "8.8.8.8:53"
upstream_dns:
type: "array"
items:
type: "string"
example:
- "tls://1.1.1.1"
- "tls://1.0.0.1"
version:
type: "string"
example: "0.1"
language:
type: "string"
example: "en"
Add set_upstreams_config function
2019-02-28 01:10:43 -07:00
UpstreamsConfig:
type: "object"
description: "Upstreams configuration"
required:
- "bootstrap_dns"
- "upstream_dns"
[change] control: Handle upstream config with JSON
2019-02-28 03:01:41 -07:00
- "all_servers"
Add set_upstreams_config function
2019-02-28 01:10:43 -07:00
properties:
bootstrap_dns:
[change] control: Handle upstream config with JSON
2019-02-28 03:01:41 -07:00
type: "array"
description: 'Bootstrap servers, port is optional after colon. Empty value will reset it to default values'
items:
type: "string"
example:
- "8.8.8.8:53"
- "1.1.1.1:53"
Add set_upstreams_config function
2019-02-28 01:10:43 -07:00
upstream_dns:
type: "array"
[change] control: Handle upstream config with JSON
2019-02-28 03:01:41 -07:00
description: 'Upstream servers, port is optional after colon. Empty value will reset it to default values'
Add set_upstreams_config function
2019-02-28 01:10:43 -07:00
items:
type: "string"
example:
- "tls://1.1.1.1"
- "tls://1.0.0.1"
all_servers:
type: "boolean"
[change] control: Handle upstream config with JSON
2019-02-28 03:01:41 -07:00
description: "If true, parallel queries to all configured upstream servers are enabled"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
Filter:
type: "object"
description: "Filter subscription info"
required:
- "enabled"
- "id"
- "lastUpdated"
- "name"
- "rulesCount"
- "url"
properties:
enabled:
type: "boolean"
id:
type: "integer"
example: 1234
lastUpdated:
type: "string"
format: "date-time"
example: "2018-10-30T12:18:57.223101822+03:00"
name:
type: "string"
example: "AdGuard Simplified Domain Names filter"
rulesCount:
type: "integer"
example: 5912
url:
type: "string"
example: "https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt"
FilteringStatus:
type: "object"
description: "Filtering settings"
required:
- "enabled"
- "filters"
- "user_rules"
properties:
enabled:
type: "boolean"
filters:
type: "array"
items:
$ref: "#/definitions/Filter"
user_rules:
type: "array"
items:
type: "string"
example:
- '||example.org^'
- '||example.com^'
Added version.json
2018-11-26 03:22:14 -07:00
VersionInfo:
type: "object"
description: "Information about the latest available version of AdGuard Home"
required:
- "version"
- "announcement"
- "announcement_url"
- "download_darwin_amd64"
- "download_linux_amd64"
- "download_linux_386"
- "download_linux_arm"
- "selfupdate_min_version"
properties:
version:
type: "string"
example: "v0.9"
announcement:
type: "string"
example: "AdGuard Home v0.9 is now available!"
announcement_url:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/tag/v0.9"
download_darwin_amd64:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.9/AdGuardHome_v0.9_MacOS.zip"
download_linux_amd64:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.9/AdGuardHome_v0.9_linux_amd64.tar.gz"
download_linux_386:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.9/AdGuardHome_v0.9_linux_386.tar.gz"
download_linux_arm:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.9/AdGuardHome_v0.9_linux_arm.tar.gz"
selfupdate_min_version:
type: "string"
example: "v0.0"
Added more definitions
2018-11-25 12:30:08 -07:00
Stats:
type: "object"
description: "General server stats for the last 24 hours"
required:
- "dns_queries"
- "blocked_filtering"
- "replaced_safebrowsing"
- "replaced_parental"
- "replaced_safesearch"
- "avg_processing_time"
properties:
dns_queries:
type: "integer"
description: "Total number of DNS queries"
example: 123
blocked_filtering:
type: "integer"
description: "Number of requests blocked by filtering rules"
example: 50
replaced_safebrowsing:
type: "integer"
description: "Number of requests blocked by the safebrowsing module"
example: 5
replaced_parental:
type: "integer"
description: "Number of blocked adult websites"
example: 15
avg_processing_time:
type: "number"
format: "float"
Added more openapi definitions
2018-11-25 14:08:47 -07:00
description: "Average time in milliseconds on processing a DNS"
Added more definitions
2018-11-25 12:30:08 -07:00
example: 0.34
StatsTop:
type: "object"
description: "Server stats top charts"
required:
- "top_queried_domains"
- "top_clients"
- "top_blocked_domains"
properties:
top_queried_domains:
type: "array"
items:
type: "object"
example:
example.org: 12312
example.com: 321
example.net: 5555
top_clients:
type: "array"
items:
type: "object"
example:
127.0.0.1: 12312
192.168.0.1: 13211
192.168.0.3: 13211
top_blocked_domains:
type: "array"
items:
type: "object"
example:
example.org: 12312
example.com: 321
example.net: 5555
Added more openapi definitions
2018-11-25 14:08:47 -07:00
StatsHistory:
type: "object"
description: "Historical stats of the DNS server. Example below is for 5 minutes. Values are from oldest to newest."
required:
- "dns_queries"
- "blocked_filtering"
- "replaced_safebrowsing"
- "replaced_parental"
- "replaced_safesearch"
- "avg_processing_time"
properties:
dns_queries:
type: "array"
items:
type: "integer"
example:
- 1201
- 1501
- 1251
- 1231
- 120
blocked_filtering:
type: "array"
items:
type: "integer"
example:
- 421
- 124
- 5
- 12
- 43
replaced_safebrowsing:
type: "array"
items:
type: "integer"
example:
- 1
- 0
- 5
- 0
- 0
replaced_parental:
type: "array"
items:
type: "integer"
example:
- 120
- 10
- 5
- 12
- 1
replaced_safesearch:
type: "array"
items:
type: "integer"
example:
- 1
- 0
- 0
- 0
- 5
avg_processing_time:
type: "array"
items:
type: "number"
format: "float"
example:
- 1.25
- 5.12
- 4.12
- 123.12
- 0.12
Added more definitions
2018-11-25 12:30:08 -07:00
DhcpConfig:
type: "object"
description: "Built-in DHCP server configuration"
required:
- "enabled"
- "gateway_ip"
- "subnet_mask"
- "range_start"
- "range_end"
- "lease_duration"
properties:
enabled:
type: "boolean"
gateway_ip:
type: "string"
example: "192.168.1.1"
subnet_mask:
type: "string"
example: "255.255.255.0"
range_start:
type: "string"
example: "192.168.1.2"
range_end:
type: "string"
example: "192.168.10.50"
lease_duration:
type: "string"
example: "12h"
DhcpLease:
type: "object"
description: "DHCP lease information"
required:
- "mac"
- "ip"
- "hostname"
- "expires"
properties:
mac:
type: "string"
example: "001109b3b3b8"
ip:
type: "string"
example: "192.168.1.22"
hostname:
type: "string"
example: "dell"
expires:
type: "string"
format: "date-time"
example: "2017-07-21T17:32:28Z"
DhcpStatus:
type: "object"
Added more openapi definitions
2018-11-25 14:08:47 -07:00
description: "Built-in DHCP server configuration and status"
Added more definitions
2018-11-25 12:30:08 -07:00
required:
- "config"
- "leases"
properties:
config:
$ref: "#/definitions/DhcpConfig"
leases:
type: "array"
items:
$ref: "#/definitions/DhcpLease"
Finished reworking openapi, added DHCP methods there
2018-11-26 02:48:17 -07:00
DhcpSearchResult:
type: "object"
description: "Information about a DHCP server discovered in the current network"
required:
- "found"
properties:
found:
type: "boolean"
gateway_ip:
type: "string"
example: "192.168.1.1"
Added more openapi definitions
2018-11-25 14:08:47 -07:00
DnsAnswer:
type: "object"
description: "DNS answer section"
properties:
ttl:
type: "integer"
example: 55
type:
type: "string"
example: "A"
value:
type: "string"
example: "217.69.139.201"
DnsQuestion:
type: "object"
description: "DNS question section"
properties:
class:
type: "string"
example: "IN"
host:
type: "string"
example: "example.org"
type:
type: "string"
example: "A"
QueryLogItem:
type: "object"
description: "Query log item"
properties:
answer:
type: "array"
items:
$ref: "#/definitions/DnsAnswer"
client:
type: "string"
example: "192.168.0.1"
elapsedMs:
type: "string"
example: "54.023928"
question:
$ref: "#/definitions/DnsQuestion"
filterId:
type: "integer"
example: 123123
description: "In case if there's a rule applied to this DNS request, this is ID of the filter that rule belongs to."
rule:
type: "string"
example: "||example.org^"
description: "Filtering rule applied to the request (if any)"
reason:
type: "string"
description: "DNS filter status"
enum:
- "NotFilteredNotFound"
- "NotFilteredWhiteList"
- "NotFilteredError"
- "FilteredBlackList"
- "FilteredSafeBrowsing"
- "FilteredParental"
- "FilteredInvalid"
- "FilteredSafeSearch"
status:
type: "string"
description: "DNS response status"
example: "NOERROR"
time:
type: "string"
description: "DNS request processing start time"
example: "2018-11-26T00:02:41+03:00"
QueryLog:
type: "array"
description: "Query log"
items:
Added openapi description
2019-02-21 07:33:46 -07:00
$ref: "#/definitions/QueryLogItem"
TlsConfig:
type: "object"
description: "TLS configuration settings and status"
properties:
# TLS configuration
enabled:
type: "boolean"
example: "true"
description: "enabled is the encryption (DOT/DOH/HTTPS) status"
server_name:
type: "string"
example: "example.org"
description: "server_name is the hostname of your HTTPS/TLS server"
force_https:
type: "boolean"
example: "true"
description: "if true, forces HTTP->HTTPS redirect"
port_https:
type: "integer"
format: "int32"
example: 443
description: "HTTPS port. If 0, HTTPS will be disabled."
port_dns_over_tls:
type: "integer"
format: "int32"
example: 853
description: "DNS-over-TLS port. If 0, DOT will be disabled."
certificate_chain:
type: "string"
description: "Base64 string with PEM-encoded certificates chain"
private_key:
type: "string"
description: "Base64 string with PEM-encoded private key"
# Below goes validation fields
valid_cert:
type: "boolean"
example: "true"
description: "valid_cert is true if the specified certificates chain is a valid chain of X509 certificates"
valid_chain:
type: "boolean"
example: "true"
description: "valid_chain is true if the specified certificates chain is verified and issued by a known CA"
subject:
type: "string"
example: "CN=example.org"
description: "subject is the subject of the first certificate in the chain"
issuer:
type: "string"
example: "CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US"
description: "issuer is the issuer of the first certificate in the chain"
not_before:
type: "string"
example: "2019-01-31T10:47:32Z"
description: "not_before is the NotBefore field of the first certificate in the chain"
not_after:
type: "string"
example: "2019-05-01T10:47:32Z"
description: "not_after is the NotAfter field of the first certificate in the chain"
dns_names:
type: "array"
items:
type: "string"
description: "dns_names is the value of SubjectAltNames field of the first certificate in the chain"
example:
- "*.example.org"
valid_key:
type: "boolean"
example: "true"
description: "valid_key is true if the key is a valid private key"
key_type:
type: "string"
example: "RSA"
description: "key_type is either RSA or ECDSA"
warning_validation:
type: "string"
example: "You have specified an empty certificate"
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
description: "warning_validation is a validation warning message with the issue description"
* tlsConfigStatus.usable is public, renamed ("ValidPair") and is exported to json ("valid_pair")
2019-02-27 07:36:02 -07:00
valid_pair:
type: "boolean"
example: "true"
description: "valid_pair is true if both certificate and private key are correct"
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
NetInterface:
type: "object"
description: "Network interface info"
properties:
flags:
type: "string"
example: "up|broadcast|multicast"
hardware_address:
type: "string"
example: "52:54:00:11:09:ba"
mtu:
type: "integer"
format: "int32"
example: 1500
name:
type: "string"
example: "eth0"
ip_addresses:
type: "array"
items:
type: "string"
example:
- "127.0.0.1"
AddressInfo:
type: "object"
description: "Port information"
properties:
ip:
type: "string"
- openapi: fix typo
2019-03-20 03:54:23 -07:00
example: "127.0.0.1"
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
port:
type: "integer"
format: "int32"
example: 53
warning:
type: "string"
example: "Cannot bind to this port"
AddressesInfo:
type: "object"
description: "AdGuard Home addresses configuration"
properties:
dns:
$ref: "#/definitions/AddressInfo"
web:
$ref: "#/definitions/AddressInfo"
interfaces:
type: "object"
description: "Network interfaces dictionary (key is the interface name)"
additionalProperties:
$ref: "#/definitions/NetInterface"
+ control: /clients: get the list of clients' IP addresses and names from /etc/hosts
2019-03-19 08:47:22 -07:00
Client:
type: "object"
description: "Client information"
properties:
ip:
type: "string"
description: "IP address"
example: "127.0.0.1"
name:
type: "string"
description: "Name"
example: "localhost"
Clients:
type: "array"
items:
$ref: "#/definitions/Client"
description: "Clients array"
Added install methods to openapi.yaml Print all net interfaces when bind_host is 0.0.0.0
2019-02-22 07:59:42 -07:00
InitialConfiguration:
type: "object"
description: "AdGuard Home initial configuration (for the first-install wizard)"
properties:
dns:
$ref: "#/definitions/AddressInfo"
web:
$ref: "#/definitions/AddressInfo"
username:
type: "string"
description: "Basic auth username"
example: "admin"
password:
type: "string"
description: "Basic auth password"
example: "password"
Reference in New Issue Copy Permalink