pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

The domainlist endpoints now return the same data that would be returned via GET on success. This brings a more uniform experience.

Browse Source 
Signed-off-by: DL6ER <dl6er@dl6er.de>
This commit is contained in:
DL6ER
2020-06-17 19:45:45 +02:00
parent febfd6addb
commit efa45649bf
4 changed files with 74 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/dns/cacheinfo.md
+1 -1
View File
@@ -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 <your-access-token>"
```
docs/api/dns/status.md
+29 -11
View File
@@ -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
}
}
```
<!-- markdownlint-enable code-block-style -->
@@ -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 <your-access-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 = '<your-access-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.
<!-- markdownlint-enable code-block-style -->
{!abbreviations.md!}
docs/api/domainlists.md
+32 -27
View File
@@ -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 <your-access-token>"
```
@@ -104,7 +104,7 @@ The domain/regex to be listed is specified through the URL (`<domain>`).
=== "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 <your-access-token>"
```
@@ -156,14 +156,23 @@ The domain/regex to be listed is specified through the URL (`<domain>`).
```
<!-- markdownlint-enable code-block-style -->
## 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
<!-- markdownlint-disable code-block-style -->
@@ -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 <your-access-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.
<!-- markdownlint-enable code-block-style -->
---
@@ -265,8 +279,7 @@ The domain/regex to be removed is specified through the URL (`<domain>`).
``` 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 <your-access-token>"
```
@@ -274,8 +287,7 @@ The domain/regex to be removed is specified through the URL (`<domain>`).
``` 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 <your-access-token>"
```
@@ -314,14 +326,7 @@ The domain/regex to be removed is specified through the URL (`<domain>`).
!!! 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)"
docs/api/index.md
+12 -10
View File
@@ -18,7 +18,7 @@ The Authorization HTTP header can be specified with `Token <your-access-token>`
=== "cURL"
``` bash
curl http://pi.hole/admin/api/dns/status \
curl -X GET http://pi.hole/admin/api/dns/status \
-H "Authorization: Token <your-access-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
}
```