diff --git a/docs/api/dns/cacheinfo.md b/docs/api/dns/cacheinfo.md index e5cba78..5aa8b76 100644 --- a/docs/api/dns/cacheinfo.md +++ b/docs/api/dns/cacheinfo.md @@ -18,7 +18,7 @@ None === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/dns/cacheinfo \ + curl -X GET http://pi.hole:8080/admin/api/dns/cacheinfo \ -H "Authorization: Token " ``` diff --git a/docs/api/dns/status.md b/docs/api/dns/status.md index 4fbc543..60b41df 100644 --- a/docs/api/dns/status.md +++ b/docs/api/dns/status.md @@ -18,7 +18,7 @@ None === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/dns/blocking + curl -X GET http://pi.hole:8080/admin/api/dns/blocking ``` === "Python 3" @@ -39,7 +39,20 @@ None ``` json { - "status": "active" + "blocking": true, + "timer": null + } + ``` + + If there is currently a timer running, the reply will be like + + ``` json + { + "blocking": false, + "timer": { + "delay": 5, + "blocking_target": true + } } ``` @@ -52,10 +65,10 @@ Requires authorization: Yes ### Parameters -Name | Required | Type | Description | Default | Example ----- | -------- | ---- | ----------- | ------- | ------- -`status` | Yes | String | Requested status | | `active` or `inactive` -`delay` | Optional | Number | Requested delay until opposite status is active | `0` | `100` (seconds) +Name | Required | Type | Description | Example +---- | -------- | ---- | ----------- | ------- +`blocking` | Yes | Boolean | Requested status | `true` +`delay` | Optional | Number | Requested delay until opposite status is active, running timer can be disabled by setting delay to `-1` | `100` (seconds) ### Example @@ -65,11 +78,10 @@ Name | Required | Type | Description | Default | Example === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/dns/blocking \ - -X POST \ + curl -X POST http://pi.hole:8080/admin/api/dns/blocking \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ - -d '{"status":"active", "delay":30}' + -d '{"blocking":false, "delay":30}' ``` === "Python 3" @@ -80,7 +92,7 @@ Name | Required | Type | Description | Default | Example URL = 'http://pi.hole:8080/admin/api/dns/blocking' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} - data = {"status":"active", "delay":30} + data = {"blocking":False, "delay":30} response = requests.post(URL, json=data, headers=HEADERS) @@ -93,9 +105,15 @@ Name | Required | Type | Description | Default | Example ``` json { - "status": "active" + "blocking": false, + "timer": { + "delay": 30, + "blocking_target": true + } } ``` + + Remember that `timer` may be `null` if there is no active timer. {!abbreviations.md!} diff --git a/docs/api/domainlists.md b/docs/api/domainlists.md index 3c927da..fe07cdb 100644 --- a/docs/api/domainlists.md +++ b/docs/api/domainlists.md @@ -23,7 +23,7 @@ None === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/whitelist/exact \ + curl -X GET http://pi.hole:8080/admin/api/whitelist/exact \ -H "Authorization: Token " ``` @@ -104,7 +104,7 @@ The domain/regex to be listed is specified through the URL (``). === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/whitelist/exact/whitelisted.com \ + curl -X GET http://pi.hole:8080/admin/api/whitelist/exact/whitelisted.com \ -H "Authorization: Token " ``` @@ -156,14 +156,23 @@ The domain/regex to be listed is specified through the URL (``). ``` -## PUT: Add item +## POST/PATCH: Add item Resources: -- `PUT /admin/api/whitelist/exact` -- `PUT /admin/api/whitelist/regex` -- `PUT /admin/api/blacklist/exact` -- `PUT /admin/api/blacklist/regex` +**Create new entry (error on existing identical record)** + +- `POST /admin/api/whitelist/exact` +- `POST /admin/api/whitelist/regex` +- `POST /admin/api/blacklist/exact` +- `POST /admin/api/blacklist/regex` + +**Create new or update existing entry (no error on existing record)** + +- `PATCH /admin/api/whitelist/exact` +- `PATCH /admin/api/whitelist/regex` +- `PATCH /admin/api/blacklist/exact` +- `PATCH /admin/api/blacklist/regex` Requires authorization: Yes @@ -175,7 +184,6 @@ Name | Required | Type | Description | Default | Example `enabled` | Optional | Boolean | Should this domain be used? | `true` | `true` `comment` | Optional | String | Comment for this domain | `null` | `Some text` - ### Example @@ -184,8 +192,7 @@ Name | Required | Type | Description | Default | Example === "cURL" ``` bash - curl http://pi.hole:8080/admin/api/whitelist/exact \ - -X PUT \ + curl -X POST http://pi.hole:8080/admin/api/whitelist/exact \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ -d '{"domain":"whitelisted.com", "enabled":true, "comment":"Some text"}' @@ -201,7 +208,7 @@ Name | Required | Type | Description | Default | Example HEADERS = {'Authorization': f'Token {TOKEN}'} data = {"domain":"whitelisted.com", "enabled":True, "comment":"Some text"} - response = requests.put(URL, json=data, headers=HEADERS) + response = requests.post(URL, json=data, headers=HEADERS) print(response.json()) ``` @@ -211,10 +218,15 @@ Name | Required | Type | Description | Default | Example Response code: `HTTP/1.1 201 Created` ``` json - { - "key": "added", - "domain": "whitelisted.com" - } + [ + { + "domain": "whitelisted.com", + "enabled": true, + "date_added": 1589108911, + "date_modified": 1589108911, + "comment": "" + } + ] ``` !!! failure "Error response (duplicated domain)" @@ -235,6 +247,8 @@ Name | Required | Type | Description | Default | Example } } ``` + + When using `PATCH` instead of `POST`, duplicate domains are silently replaced without triggering an error. --- @@ -265,8 +279,7 @@ The domain/regex to be removed is specified through the URL (``). ``` bash domain="whitelisted.com" - curl http://pi.hole:8080/admin/api/whitelist/exact/${domain} \ - -X DELETE \ + curl -X DELETE http://pi.hole:8080/admin/api/whitelist/exact/${domain} \ -H "Authorization: Token " ``` @@ -274,8 +287,7 @@ The domain/regex to be removed is specified through the URL (``). ``` bash regex="$(echo -n "(^|\\.)facebook.com$" | jq -sRr '@uri')" - curl http://pi.hole:8080/admin/api/whitelist/exact/${regex} \ - -X DELETE \ + curl -X DELETE http://pi.hole:8080/admin/api/whitelist/exact/${regex} \ -H "Authorization: Token " ``` @@ -314,14 +326,7 @@ The domain/regex to be removed is specified through the URL (``). !!! success "Success response" - Response code: `HTTP/1.1 200 OK` - - ``` json - { - "key": "removed", - "domain": "whitelisted.com" - } - ``` + Response code: `HTTP/1.1 204 No Content` !!! failure "Error response (database permission error)" diff --git a/docs/api/index.md b/docs/api/index.md index 97008d8..d2429bc 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -18,7 +18,7 @@ The Authorization HTTP header can be specified with `Token ` === "cURL" ``` bash - curl http://pi.hole/admin/api/dns/status \ + curl -X GET http://pi.hole/admin/api/dns/status \ -H "Authorization: Token " ``` @@ -73,14 +73,16 @@ Some `4xx` errors that could be handled programmatically include an error code t Code | Description | Interpretation ---- | ----------- | -------------- -`200` | `OK` | Everything worked as expected. -`400` | `Bad Request` | The request was unacceptable, often due to a missing required parameter. -`401` | `Unauthorized` | No valid API key provided for endpoint requiring authorization. -`402` | `Request Failed` | The parameters were valid but the request failed. -`403` | `Forbidden` | The API key doesn't have permissions to perform the request. -`404` | `Not Found` | The requested resource doesn't exist. -`429` | `Too Many Requests` | Too many requests hit the API too quickly. -`500`, `502`, `503`, `504` | `Server Errors` | Something went wrong on Pi-hole's end. (These are rare.) +`200` | `OK` | Everything worked as expected +`201` | `Content Created` | Added a new item +`204` | `No Content` | Removed an item +`400` | `Bad Request` | The request was unacceptable, often due to a missing required parameter +`401` | `Unauthorized` | No valid API key provided for endpoint requiring authorization +`402` | `Request Failed` | The parameters were valid but the request failed +`403` | `Forbidden` | The API key doesn't have permissions to perform the request +`404` | `Not Found` | The requested resource doesn't exist +`429` | `Too Many Requests` | Too many requests hit the API too quickly +`500`, `502`, `503`, `504` | `Server Errors` | Something went wrong on Pi-hole's end (These are rare) ### JSON response @@ -93,7 +95,7 @@ The form of replies to successful requests strongly depends on the selected endp ``` json { - "status": "enabled" + "blocking": true } ```