diff --git a/docs/api/auth.md b/docs/api/auth.md index 3e55184..3989794 100644 --- a/docs/api/auth.md +++ b/docs/api/auth.md @@ -41,7 +41,7 @@ As a result, the password itself is never transmitted plain-text. Eavesdropping > > Now, the annual energy output of our sun is about $1.21\cdot 10^{41}$ ergs. This is enough to power about $2.7\cdot 10^{56}$ single bit changes on our ideal computer; enough state changes to put a 187-bit counter through all its values. If we built a Dyson sphere around the sun and captured all of its energy for 32 years, without any loss, we could power a computer to count up to $2^{192}$. Of course, it wouldn’t have the energy left over to perform any useful calculations with this counter. > - > But that’s just one star, and a measly one at that. A typical supernova releases something like $10^{51}$ ergs. (About a hundred times as much energy would be released in the form of neutrinos, but let them go for now.) If all of this energy could be channeled into a single orgy of computation, a `219`-bit counter could be cycled through all of its states. + > But that’s just one star, and a measly one at that. A typical supernova releases something like $10^{51}$ ergs. (About a hundred times as much energy would be released in the form of neutrinos, but let them go for now.) If all of this energy could be channeled into a single orgy of computation, a 219-bit counter could be cycled through all of its states. > > These numbers have nothing to do with the technology of the devices; they are the maximums that thermodynamics will allow. And they strongly imply that **brute-force attacks against 256-bit keys will be *infeasible* until computers are built from something other than matter and occupy something other than space**. diff --git a/docs/api/dns/cache.md b/docs/api/dns/cache.md index 4882508..e0cb046 100644 --- a/docs/api/dns/cache.md +++ b/docs/api/dns/cache.md @@ -1,5 +1,3 @@ -# DNS - Cache Info - `pihole-FTL` offers an efficient DNS cache that helps speed up your Internet experience. This DNS cache is part of the embedded `dnsmasq` server. Setting the cache size to zero disables caching. The DNS TTL value is used for determining the caching period. `pihole-FTL` clears its cache on receiving `SIGHUP`. diff --git a/docs/api/domains.md b/docs/api/domains.md index a2a1f51..efc2ded 100644 --- a/docs/api/domains.md +++ b/docs/api/domains.md @@ -222,10 +222,10 @@ **Create new entry (error on existing identical record)** -- `POST /api/domains/allow/exact/` -- `POST /api/domains/allow/regex/` -- `POST /api/domains/allow/exact/` -- `POST /api/domains/allow/regex/` +- `POST /api/domains/allow/exact` +- `POST /api/domains/allow/regex` +- `POST /api/domains/allow/exact` +- `POST /api/domains/allow/regex` ???+ example "🔒 Request" @@ -233,11 +233,10 @@ === "cURL" ``` bash - domain="allowed2.com" - curl -X POST http://pi.hole/api/domains/allow/exact/${domain} \ + curl -X POST http://pi.hole/api/domains/allow/exact \ -d sid=$sid \ -H "Content-Type: application/json" \ - -d '{"enabled": true, "comment": "Some text"}' + -d '{"domain": "allowed2.com", "enabled": true, "comment": "Some text"}' ``` === "Python 3" @@ -245,10 +244,10 @@ ``` python import requests - domain = "allowed2.com" - url = 'http://pi.hole:8080/api/domains/allow/exact/' + domain + url = 'http://pi.hole:8080/api/domains/allow/exact' sid = '' data = { + "item": "allowed2.com", "enabled": True, "comment": "Some text", "sid": sid @@ -261,6 +260,9 @@ **Optional parameters** + ??? info "Domain/regex (`"item": string`)" + Domain or regex to be added. When this is a regular expression, ensure it is properly JSON-escaped. + ??? info "Enabled (`"enabled": boolean`)" Whether this item should enabled or not. @@ -309,7 +311,7 @@ } ``` - !!! hint "Hint: Use `PUT` instead of `POST`" + !!! hint "Hint: Use `PUT` instead of `POST` to avoid unique constraints" When using `PUT` instead of `POST`, duplicate domains are silently replaced without issuing an error. diff --git a/docs/api/index.md b/docs/api/index.md index c99d9e7..1fe2801 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,6 +1,6 @@ # API Reference -The Pi-hole API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 [JSON-encoded](http://www.json.org/) data for all API responses, and uses standard HTTP response codes and verbs. +The Pi-hole API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 [JavaScript Object Notation (JSON)-encoded](http://www.json.org/) data for all API responses, and uses standard HTTP response codes and verbs. Most (but not all) endpoints require authentication. API endpoints requiring authentication will fail with code `401 Unauthorized` if no key is supplied. @@ -110,7 +110,7 @@ In contrast, errors have a uniform style to ease their programatic treatment: ## HTTP methods used by this API -Each HTTP request consists of a method that indicates the action to be performed on the identified resource. The relevant standards are [RFC 2616, Scn. 9](https://tools.ietf.org/html/rfc2616#section-9) (`GET/POST/PUT/DELETE`). +Each HTTP request consists of a method that indicates the action to be performed on the identified resource. The relevant standards is [RFC 2616](https://tools.ietf.org/html/rfc2616). Though, RFC 2616 has been very clear in differentiating between the methods, complex wordings are a source of confusion for many users. Pi-hole's API uses the methods like this: @@ -118,37 +118,53 @@ Method | Description ---------|------------ `GET` | **Read** from resource. The resource may not exist. `POST` | **Create** resources -`PUT` | **Create or Replace** the resource. This method commonly used to *update* entries. +`PUT` | **Create or Replace** a resource. This method is commonly used to *update* entries. `DELETE` | **Delete** existing resource -### `GET` + +??? info "Summarized details from [RFC 2616, Scn. 9](https://tools.ietf.org/html/rfc2616#section-9) (`GET/POST/PUT/DELETE`)" + ### `GET` -The `GET` method means retrieve whatever information (in the form of an entity) that is identified by the Request-URI. + The `GET` method means retrieve whatever information (in the form of an entity) that is identified by the URI. -### `POST` + As `GET` requests do not change the state of the resource, these are said to be **safe methods**. Additionally, `GET` requests are **idempotent**, which means that making multiple identical requests must produce the same result every time until another method (`POST` or `PUT`) has changed the state of the resource on the server. -The `POST` method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. `POST` is designed to allow a uniform method to cover the following functions: + For any given HTTP `GET`, if the resource is found on the server, then the API returns HTTP response code `200 (OK)` – along with the response body. -- Annotation of existing resources; -- Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles; -- Providing a block of data, such as the result of submitting a form, to a data-handling process; -- Extending a database through an append operation. + In case a resource is NOT found on server, then the API returns HTTP response code `404 (Not found)`. Similarly, if it is determined that `GET` request itself is not correctly formed then API will return HTTP response code `400 (Bad request)`. -If a resource has been created on the origin server, the response will be `201 (Created)`. + ### `POST` -Not all action performed using the `POST` method will result in a resource that can be identified by a URI. In such a case, either `200 (OK)` or `204 (No Content)` is the appropriate response status, depending on whether or not the response includes an entity that describes the result. + Use `POST` APIs to **create new subordinate records**, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table. W`POST` methods are used to create a new resource into the collection of resources. -### `PUT` + If a resource has been created on the origin server, the response will be `201 (Created)`. + Not all action performed using the `POST` method will result in a resource that can be identified by a URI. In such a case, either `200 (OK)` or `204 (No Content)` is the appropriate response status, depending on whether or not the response includes an entity that describes the result. -The `PUT` method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity will be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. + Note that `POST` is **neither safe nor idempotent**, and invoking two identical `POST` requests typically results in an error. -The origin server will inform the user agent via a `200 (OK)` response if processing the entry was successful. + ### `PUT` -### `DELETE` + Use `PUT` primarily to **update existing records** (if the resource does not exist, the API will typically create a new record for it). If a new record has been added at the given URI, or an existing resource is modified, either the `200 (OK)` or `204 (No Content)` response codes are sent to indicate successful completion of the request. -The `DELETE` method requests that the origin server delete the resource identified by the Request-URI. The API will not indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location. + ### `DELETE` -A successful response will be `200 (OK)` if the response includes an entity describing the status, `202 (Accepted)` if the action has not yet been enacted, or `204 (No Content)` if the action has been enacted but the response does not include an entity. + As the name applies, `DELETE` APIs are used to **delete records** (identified by the Request-URI). + + A successful response will be `200 (OK)` if the response includes an entity describing the status, `202 (Accepted)` if the action has not yet been enacted, or `204 (No Content)` if the action has been enacted but the response does not include an entity. + + `DELETE` operations are **idempotent**. If you `DELETE` a resource, it’s removed from the collection of resources. Repeatedly calling `DELETE` on that resource will not change the outcome – however, calling `DELETE` on a resource a second time *may* return a 404 (NOT FOUND) since it was already removed. + +???+ info "Example" + Let’s list down few URIs and their purpose to get better understanding when to use which method: + + Method + URI | Interpretation + ---------------------|-------------------- + `GET /api/groups` | Get all groups + `POST /api/groups` | Create a new group + `GET /api/groups/abc` | Get the group `abc` + `PUT /api/groups/abc` | Update the group `abc` + `DELETE /api/groups/abc` | Delete group `abc` + ## Error handling