POST should not include the target to get pushed

Signed-off-by: DL6ER <[email protected]>

Author: DL6ER

Diff for: 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**.
 <!-- markdownlint-enable code-block-style -->

Diff for: 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`.
 
 <!-- markdownlint-disable code-block-style -->

Diff for: docs/api/domains.md

@@ -222,33 +222,32 @@
 
 **Create new entry (error on existing identical record)**
 
-- `POST /api/domains/allow/exact/<domain or regex>`
-- `POST /api/domains/allow/regex/<domain or regex>`
-- `POST /api/domains/allow/exact/<domain or regex>`
-- `POST /api/domains/allow/regex/<domain or regex>`
+- `POST /api/domains/allow/exact`
+- `POST /api/domains/allow/regex`
+- `POST /api/domains/allow/exact`
+- `POST /api/domains/allow/regex`
 
 <!-- markdownlint-disable code-block-style -->
 ???+ example "🔒 Request"
 
     === "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"
 
         ``` 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 = '<valid session id>'
         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.
 <!-- markdownlint-enable code-block-style -->
 

Diff for: 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,45 +110,61 @@ 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:
 
 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`
+<!-- markdownlint-disable code-block-style -->
+??? 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 URI.
+
+    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 `GET` method means retrieve whatever information (in the form of an entity) that is identified by the Request-URI.
+    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.
 
-### `POST`
+    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)`.
 
-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:
+    ### `POST`
 
-- 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.
+    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.
 
-If a resource has been created on the origin server, the response will be `201 (Created)`.
+    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.
 
-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.
+    Note that `POST` is **neither safe nor idempotent**, and invoking two identical `POST` requests typically results in an error.
 
-### `PUT`
+    ### `PUT`
 
-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.
+    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 origin server will inform the user agent via a `200 (OK)` response if processing the entry was successful.
+    ### `DELETE`
 
-### `DELETE`
+    As the name applies, `DELETE` APIs are used to **delete records** (identified by the Request-URI).
 
-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.
+    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.
 
-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`
+<!-- markdownlint-enable code-block-style -->
 
 ## Error handling