Fix inaccuracies, reorganize sections and headers.

1 files changed, 30 insertions, 29 deletions

diff --git a/docs/appendix/http-api.rst b/docs/appendix/http-api.rst
index 1a78fecc..e9e4e653 100644
--- a/docs/appendix/http-api.rst
+++ b/docs/appendix/http-api.rst
@@ -36,7 +36,7 @@ viable). Omitting any of listen-address, listen-port, or server-name, will
 leave appropriate defaults in the nginx directive. Multiple instances of
 ``service https api-restrict virtual-host`` may be set.
 
-Operational requests
+Configuration mode requests
 --------------------
 
 In our example, we are creating a dummy interface and assigning an address to it:
@@ -57,87 +57,88 @@ Separate value field make the semantics more clear though, and also makes it eas
 
 You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit.
 
-
-Configuration management requests
----------------------------------
-
-When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command.
-
-If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example:
+To retrieve a value:
 
 .. code-block:: none
 
-  # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file
+  curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
 
+Use ``returnValues`` for multi-valued nodes.
 
 
-Reading config
---------------
+Show config
+"""""""""""
 
-To retrieve raw configs:
+To retrieve the full config under a path:
 
 .. code-block:: none
 
-  # curl -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
+  # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
  
-It will returns: 
+It will return: 
 
 .. code-block:: none
 
-  {"success": true, "data": " /* So very dummy */\n dummy dum0 {\n     address 192.168.168.1/32\n     address 192.168.168.2/32\n     /* That is a description */\n     description \"Test interface\"\n }\n dummy dum1 {\n     address 203.0.113.76/32\n     address 203.0.113.79/32\n }\n", "error": null}
+  {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null}
 
+Passing an empty path will return the full config:
+
+.. code-block:: none
 
-Opmode
-------
+  # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
+ 
 
-It is possible to run show and generate commands outside configure.
+Configuration management requests
+---------------------------------
 
+When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command.
 
-Request:
+If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example:
 
 .. code-block:: none
 
-  curl -X POST -F key=mykey https://myip/generate --insecure -F data='{"cmd": "wireguard preshared-key"}'
+  # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file
 
-Response:
 
-.. code-block:: none
+Operational mode commands
+-------------------------
+
+It is possible to run ``show`` and ``generate`` commands:
 
-  {"success": true, "data": "wxxxxxxxfHJj/aDWf0qg0=\n", "error": null}
 
 Request:
 
 .. code-block:: none
 
-  curl -X POST -F key=mykey https://myip/show --insecure -F data='{"cmd": "wireguard keypairs pubkey default"}'
+  curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate
 
 Response:
 
 .. code-block:: none
 
-  {"success": true, "data": "<<censored_but_right_key>>\n", "error": null}
+  {"success": true, "data": "", "error": null}
 
 Request:
 
 .. code-block:: none
 
-  curl -X POST -F key=mykey https://myip/show --insecure -F data='{"cmd": "wireguard keypairs pubkey default"}'
+  curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show
 
 Response:
 
 .. code-block:: none
 
-  {"success": true, "data": "<<censored_but_right_key>>\n", "error": null}
+  {"success": true, "data": "<some pubkey>=\n", "error": null} 
 
 Request:
 
 .. code-block:: none
 
-  curl -s -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=mykey https://myip:44302/show
+  curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show
 
 Response:
 
 .. code-block:: none
 
-  {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n       O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n       T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n       F - PBR, f - OpenFabric,\n       > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 10.3.0.1, eth0, 12:42:53\nC>* 10.3.0.0/24 is directly connected, eth0, 12:42:53\nS>* 10.10.10.0/24 [1/0] via 10.3.0.1, eth0, 12:42:53\nS>* 10.10.11.0/24 [1/0] via 10.3.0.1, eth0, 12:42:53\nS>* 169.254.169.254/32 [210/0] via 10.3.0.3, eth0, 12:42:53\n", "error": null}
+  {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n       O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n       T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n       F - PBR, f - OpenFabric,\n       > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null}