doc/user: move cache-clearing API docs to the API page

It seemed to clutter the cache page in docs,
even though very few users will be directly interested in the API.

diff --git a/doc/user/config-cache.rst b/doc/user/config-cache.rst
index 66de7da4cdbc6158915b816ef85321308dfc134c..500c7266e17ba4a3da174deffaa9dd84a96a3574 100644 (file)
--- a/doc/user/config-cache.rst
+++ b/doc/user/config-cache.rst
@@ -53,6 +53,16 @@ Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13
 Clearing
 --------
 
+You can use :ref:`kresctl <manager-client-commands>` to clear (parts of) the cache, e.g.:
+
+.. code-block:: none
+
+   $ kresctl cache clear example.com.
+
+   $ kresctl cache clear --help
+
+It is also possible to use HTTP API directly: :ref:`manager-api-cache-clear`.
+
 There are two specifics to purging cache records matching specified criteria:
 
 * To reliably remove negative cache entries, you need to clear the subtree with the whole zone. E.g. to clear negative cache entries for the (formerly non-existent)
@@ -60,73 +70,9 @@ There are two specifics to purging cache records matching specified criteria:
 * This operation is asynchronous and might not yet be finished when the call to the ``/cache/clear`` API endpoint returns.
   The return value indicates if clearing continues asynchronously or not.
 
-.. tip::
-
-   Use :ref:`manager-client` to clear the cache.
-
-   .. code-block:: none
-
-      $ kresctl cache clear example.com.
-
 .. [#] This is a consequence of DNSSEC negative cache which relies on proofs of non-existence on various owner nodes. It is impossible to efficiently flush part of DNS zones signed with NSEC3.
 
 
-Parameters
-``````````
-Parameters for cache clearance are in JSON and are sent with the HTTP request as its body.
-
-.. option:: "name": "<name>"
-
-   Optional, subtree to purge; if the name isn't provided, whole cache is purged (and any other parameters are disregarded).
-
-.. option:: "exact-name": true|false
-
-   :default: false
-
-   If set to ``true``, only records with *the same* name are removed.
-
-.. option:: "rr-type": "<rr-type>"
-
-   Optional, you may additionally specify the type to remove, but that is only supported with :option:`exact-name <"exact-name": true|false>` enabled.
-
-.. option:: "chunk-size": <integer>
-
-   :default: 100
-
-   The number of records to remove in a single round. The purpose is not to block the resolver for too long.
-   By default, the resolver repeats the command after at least one millisecond until all the matching data is cleared.
-
-Return value
-````````````
-
-The return value is an object with the following fields. The ``count`` field is
-always present.
-
-.. option:: "count": integer
-
-   The number of items removed from the cache by this call (may be 0 if no entry matched criteria).
-
-   Always present.
-
-.. option:: "not_apex": true|false
-
-   Cleared subtree is not cached as zone apex; proofs of non-existence were probably not removed.
-
-   Optional. Considered ``false`` when not present.
-
-.. option:: "subtree": "<zone_apex>"
-
-   Hint where zone apex lies (this is an estimation based on the cache contents and may not always be accurate).
-
-   Optional.
-
-.. option:: "chunk_limit": true|false
-
-   More than :option:`chunk-size <"chunk-size": <integer>>` items needs to be cleared, clearing will continue asynchronously.
-
-   Optional. Considered ``false`` when not present.
-
-
 .. _config-cache-persistence:
 
 Persistence

diff --git a/doc/user/manager-api.rst b/doc/user/manager-api.rst
index fb1c713b98cc8d5ac15fa9a443d5309feadd60b3..95fcd489a3c98a6b6edde0d6cbf40eb247da238e 100644 (file)
--- a/doc/user/manager-api.rst
+++ b/doc/user/manager-api.rst
@@ -29,7 +29,7 @@ What can the API do?
 - ``GET /metrics/prometheus`` provides metrics in Prometheus format
     The ``prometheus-client`` Python package needs to be installed. If not installed, it returns 404 (Not Found).
 
-- ``POST /cache/clear`` purges cache records matching the specified criteria, see :ref:`cache clearing <config-cache-clear>`
+- ``POST /cache/clear`` purges cache records matching the specified criteria, see :ref:`manager-api-cache-clear`
 
 
 Configuring the API socket
@@ -82,3 +82,64 @@ Some configuration options cannot be changed dynamically for stability or securi
 In the case of an attempt to configure such an option, the operation is rejected.
 
 
+.. _manager-api-cache-clear:
+
+Cache clearing API
+------------------
+``POST /cache/clear`` purges cache records matching the specified criteria.
+Some general properties of cache-clearance are also described at :ref:`config-cache-clear`.
+
+Parameters
+``````````
+Parameters are in JSON and sent with the HTTP request as its body.
+
+.. option:: "name": "<name>"
+
+   Optional, subtree to purge; if the name isn't provided, whole cache is purged (and any other parameters are disregarded).
+
+.. option:: "exact-name": true|false
+
+   :default: false
+
+   If set to ``true``, only records with *the same* name are removed.
+
+.. option:: "rr-type": "<rr-type>"
+
+   Optional, you may additionally specify the type to remove, but that is only supported with :option:`exact-name <"exact-name": true|false>` enabled.
+
+.. option:: "chunk-size": <integer>
+
+   :default: 100
+
+   The number of records to remove in a single round. The purpose is not to block the resolver for too long.
+   By default, the resolver repeats the command after at least one millisecond until all the matching data is cleared.
+
+Return value
+````````````
+
+The return value is an object with the following fields. The ``count`` field is
+always present.
+
+.. option:: "count": integer
+
+   The number of items removed from the cache by this call (may be 0 if no entry matched criteria).
+
+   Always present.
+
+.. option:: "not_apex": true|false
+
+   Cleared subtree is not cached as zone apex; proofs of non-existence were probably not removed.
+
+   Optional. Considered ``false`` when not present.
+
+.. option:: "subtree": "<zone_apex>"
+
+   Hint where zone apex lies (this is an estimation based on the cache contents and may not always be accurate).
+
+   Optional.
+
+.. option:: "chunk_limit": true|false
+
+   More than :option:`chunk-size <"chunk-size": <integer>>` items needs to be cleared, clearing will continue asynchronously.
+
+   Optional. Considered ``false`` when not present.