From e601281eac649b779ef49fc3fc17cb3a4e929c75 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 16 Jun 2020 23:11:52 +0200 Subject: [PATCH] Move white- and blacklist endpoints one level up Signed-off-by: DL6ER --- docs/api/{dns/lists.md => domainlists.md} | 57 ++++++++++++----------- docs/api/index.md | 5 +- 2 files changed, 32 insertions(+), 30 deletions(-) rename docs/api/{dns/lists.md => domainlists.md} (75%) diff --git a/docs/api/dns/lists.md b/docs/api/domainlists.md similarity index 75% rename from docs/api/dns/lists.md rename to docs/api/domainlists.md index 7e34544..39d6b0d 100644 --- a/docs/api/dns/lists.md +++ b/docs/api/domainlists.md @@ -4,10 +4,10 @@ Resources: -- `GET /admin/api/dns/whitelist/exact` -- `GET /admin/api/dns/whitelist/regex` -- `GET /admin/api/dns/blacklist/exact` -- `GET /admin/api/dns/blacklist/regex` +- `GET /admin/api/whitelist/exact` +- `GET /admin/api/whitelist/regex` +- `GET /admin/api/blacklist/exact` +- `GET /admin/api/blacklist/regex` Requires authorization: Yes @@ -24,7 +24,7 @@ None ``` bash curl -H "Authorization: Token " \ - http://pi.hole:8080/admin/api/dns/whitelist/exact + http://pi.hole:8080/admin/api/whitelist/exact ``` === "Python 3" @@ -32,7 +32,7 @@ None ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/whitelist/exact' + URL = 'http://pi.hole:8080/admin/api/whitelist/exact' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -57,7 +57,7 @@ None ] ``` -!!! danger "Error response (database not available)" +!!! failure "Error response (database not available)" Response code: `HTTP/1.1 402 - Request failed` @@ -78,10 +78,10 @@ None Resources: -- `PUT /admin/api/dns/whitelist/exact` -- `PUT /admin/api/dns/whitelist/regex` -- `PUT /admin/api/dns/blacklist/exact` -- `PUT /admin/api/dns/blacklist/regex` +- `PUT /admin/api/whitelist/exact` +- `PUT /admin/api/whitelist/regex` +- `PUT /admin/api/blacklist/exact` +- `PUT /admin/api/blacklist/regex` Requires authorization: Yes @@ -103,10 +103,10 @@ Name | Required | Type | Description | Default | Example ``` bash curl -X PUT \ - -H "Authorization: Token " \ - http://pi.hole:8080/admin/api/dns/whitelist/exact \ - -H "Content-Type: application/json" \ - -d @body.json + -H "Authorization: Token " \ + http://pi.hole:8080/admin/api/whitelist/exact \ + -H "Content-Type: application/json" \ + -d @body.json ``` === "Python 3" @@ -114,7 +114,7 @@ Name | Required | Type | Description | Default | Example ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/whitelist/exact' + URL = 'http://pi.hole:8080/admin/api/whitelist/exact' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} data = json.load(open('body.json', 'rb')) @@ -149,7 +149,7 @@ Name | Required | Type | Description | Default | Example } ``` -!!! danger "Error response (duplicated domain)" +!!! failure "Error response (duplicated domain)" Response code: `HTTP/1.1 402 - Request failed` @@ -175,10 +175,10 @@ Name | Required | Type | Description | Default | Example Resources: -- `DELETE /admin/api/dns/whitelist/exact/` -- `DELETE /admin/api/dns/whitelist/regex/` -- `DELETE /admin/api/dns/blacklist/exact/` -- `DELETE /admin/api/dns/blacklist/regex/` +- `DELETE /admin/api/whitelist/exact/` +- `DELETE /admin/api/whitelist/regex/` +- `DELETE /admin/api/blacklist/exact/` +- `DELETE /admin/api/blacklist/regex/` Requires authorization: Yes @@ -190,14 +190,15 @@ The domain/regex to be removed is specified through the URL (``). !!! example "Request" + === "cURL" **Domain** ``` bash curl -X DELETE \ - -H "Authorization: Token " \ - http://pi.hole:8080/admin/api/dns/whitelist/exact/whitelisted.com + -H "Authorization: Token " \ + http://pi.hole:8080/admin/api/whitelist/exact/whitelisted.com ``` **Regular expression** @@ -205,8 +206,8 @@ The domain/regex to be removed is specified through the URL (``). ``` bash regex="$(echo "(^|\\.)facebook.com$" | jq -sRr '@uri')" curl -X DELETE \ - -H "Authorization: Token " \ - http://pi.hole:8080/admin/api/dns/whitelist/exact/${regex} + -H "Authorization: Token " \ + http://pi.hole:8080/admin/api/whitelist/exact/${regex} ``` === "Python" @@ -216,7 +217,7 @@ The domain/regex to be removed is specified through the URL (``). ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/whitelist/exact/whitelisted.com' + URL = 'http://pi.hole:8080/admin/api/whitelist/exact/whitelisted.com' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -232,7 +233,7 @@ The domain/regex to be removed is specified through the URL (``). import urllib regex = urllib.parse.quote("(^|\\.)facebook.com$") - URL = 'http://pi.hole:8080/admin/api/dns/whitelist/exact/' + URL = 'http://pi.hole:8080/admin/api/whitelist/exact/' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -252,7 +253,7 @@ The domain/regex to be removed is specified through the URL (``). } ``` -!!! danger "Error response (database permission error)" +!!! failure "Error response (database permission error)" Response code: `HTTP/1.1 402 - Request failed` diff --git a/docs/api/index.md b/docs/api/index.md index 006e72e..e5325d3 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -46,7 +46,7 @@ The Authorization HTTP header can be specified with `Token ` } ``` -!!! danger "Example reply: Error (unauthorized access)" +!!! failure "Example reply: Error (unauthorized access)" Response code: `HTTP/1.1 401 Unauthorized` @@ -99,7 +99,8 @@ The form of replies to successful requests strongly depends on the selected endp In contrast, errors have a uniform appearance to ease a programatic treatment: -!!! danger "Example reply: Error (unauthorized access)" +!!! failure "Example reply: Error (unauthorized access)" + ``` json { "error": {