From ea8d486124f912d4f1e6637145a6dce00bf63197 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Mon, 20 Nov 2023 09:51:06 +0100
Subject: [PATCH] Development manual/API reference - reading reference about
 parameters and expected responses.
 https://github.com/opnsense/core/issues/7014

---
 source/development/api.rst | 46 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/source/development/api.rst b/source/development/api.rst
index 96b61e84..25af43bb 100644
--- a/source/development/api.rst
+++ b/source/development/api.rst
@@ -36,6 +36,52 @@ The $key and $secret parameters are used to pass the API credentials using curl.
 
     ACL's are explained in :doc:`development/components/acl </development/components/acl>`).
 
+Required parameters and expected responses
+------------------------------------------------
+
+Our auto-generated api documentation can only collect endpoints and their most likely call method (:code:`GET`, :code:`POST`),
+Since almost 99% of our endpoints are actually being used by the gui, it's not very complicated to find their
+parameters, you just need a browser and open an inspect pane. Calls being executed from the gui can easily be found
+by filtering the requests starting with :code:`/api/`.
+
+For exampe, when looking at the search grid in :menuselection:`System --> Diagnostics --> Services`, pressing the reload
+button will execute a :code:`POST` to :code:`https://my.firewall/api/core/service/search` containing the following raw
+json data:
+
+::
+
+    {"current":1,"rowCount":7,"sort":{},"searchPhrase":""}
+
+
+And returns a structure similar to:
+
+::
+
+    {
+        "total": 10,
+        "rowCount": 7,
+        "current": 1,
+        "rows": [
+            {
+            "id": "configd",
+            "locked": 1,
+            "running": 1,
+            "description": "System Configuration Daemon",
+            "name": "configd"
+            },
+            ....
+        ]
+    }
+
+
+A lot of endpoints use the same shared model classes underneath and will thus look quite similar. If classes are bound to
+a model, the documentation will point to it. Here you can find the standard types to expect, without specific application
+specific validations.
+
+When more detailed information is needed, best read the  :doc:`Architecture </development/architecture>` documentation to
+understand how different areas of the system interact.
+
+
 Core API
 --------