doc/gettingstarted-config: API doc update

diff --git a/doc/gettingstarted-config.rst b/doc/gettingstarted-config.rst
index 75101d410d8acb4fb3d4c029f5c4164646abfa65..b6e33ee2d3e61d0b03692b2768cd621e5a278fb3 100644 (file)
--- a/doc/gettingstarted-config.rst
+++ b/doc/gettingstarted-config.rst
@@ -25,11 +25,11 @@ The example configuration files are also installed as documentation files, typic
 Management HTTP API
 ===================
 
-You can use HTTP API to configure already running Knot Resolver.
-By default HTTP API is configured as UNIX domain socket ``manager.sock`` located in the resolver's rundir.
-This socket is used by ``kresctl`` tool.
+You can use HTTP API to dynamically change configuration of already running Knot Resolver.
+By default the API is configured as UNIX domain socket ``manager.sock`` located in the resolver's rundir (typically ``/run/knot-resolver/``).
+This socket is used by ``kresctl`` utility in default.
 
-Configuration of API can be changed only in ``/etc/knot-resolver/config.yml`` file:
+The API setting can be changed only in ``/etc/knot-resolver/config.yml`` configuration file:
 
 .. code-block:: yaml
 
@@ -38,45 +38,34 @@ Configuration of API can be changed only in ``/etc/knot-resolver/config.yml`` fi
         # or use unix socket instead of inteface
         # unix-socket: /my/new/socket.sock
 
-Configuration API is available on ``/config`` HTTP endpoint.
-All requests support ``If-Match`` HTTP header with an ETag.
-If the ETag is wrong, the request fails.
+First version of configuration API endpoint is available on ``/v1/config`` HTTP endpoint.
+Configuration API supports following HTTP request methods:
 
-API support following HTTP request methods:
-
-=============================   =========================
-HTTP request methods            Operation
-=============================   =========================
-**GET**    ``/config[/path]``   returns current config with an ETag
-**POST**   ``/config[/path]``   upsert (try update, if does not exists, insert), appends to array
-**PUT**    ``/config[/path]``   insert (fails if object already exists)
-**PATCH**  ``/config[/path]``   update (fails if object does not exist)
-**DELETE** ``/config[/path]``   delete an existing object
-=============================   =========================
+================================   =========================
+HTTP request methods               Operation
+================================   =========================
+**GET**    ``/v1/config[/path]``   returns current configuration with an ETag
+**PUT**    ``/v1/config[/path]``   upsert (try update, if does not exists, insert), appends to array
+**PATCH**  ``/v1/config[/path]``   update property using `JSON Patch <https://jsonpatch.com/>`_
+**DELETE** ``/v1/config[/path]``   delete an existing property or list item at given index
+================================   =========================
 
 .. note::
 
-    Some configuration options cannot be configured via the API for stability and security reasons(e.g. API configuration itself).
-    In the case of an attempt to configure such an option, the operation is rejected.
-
-Path
-----
-
-The configuration path is used to determine specific configuration option or subtree of configuration.
+    Managemnet API has other useful endpoints (metrics, schema, ...), see the detailed :ref:`API documentation <manager-api>`.
 
-Items in lists and dictionaries are reachable as follows and can also be combined:
+**path:**
+    Determines specific configuration option or configuration subtree on that path.
+    Items in lists and dictionaries are reachable using indexes ``/list-name/{index}/`` and keys ``/dict-name/{key}/``.
 
-* ``/list-name/{num-id}``
-* ``/dict-name/{key}``
+**payload:**
+    JSON or YAML encoding is used for configuration payload.
 
-For example, the configuration path might look like this:
-
-* ``/config/network/listen/1/interface``
+.. note::
 
-Payload
--------
+    Some configuration options cannot be configured via the API for stability and security reasons(e.g. API configuration itself).
+    In the case of an attempt to configure such an option, the operation is rejected.
 
-The API uses JSON encoding for payload. It has the same structure as YAML configuration file.
 
 ===============
 kresctl utility