API documentation erroneously provides UUID parameters whereas the UI uses the ID

[dca00]

Important notices

Before you add a new report, we ask you kindly to acknowledge the following:

• [ x] I have read the contributing guide lines at https://github.com/opnsense/core/blob/master/CONTRIBUTING.md
• [ x] I am convinced that my issue is new after having checked both open and closed issues at https://github.com/opnsense/core/issues?q=is%3Aissue

Describe the bug

A clear and concise description of what the bug is, including last known working version (if any).

Tip: to validate your setup was working with the previous version, use opnsense-revert (https://docs.opnsense.org/manual/opnsense_tools.html#opnsense-revert)

To Reproduce

Steps to reproduce the behavior:

1. Go to Firewall/Rules/any interface
2. Click F12 to open developer tools
3. Switch to the Network tab
4. Toggle any rule
5. Switch the right pane to the Request tab
6. See the 2nd parameter being the numeric ID of the rule on the screen, whereas the documentation indicates it is the UUID of the rule

Expected behavior

The documentation should be accurate

Describe alternatives you considered

N/A

Screenshots

Relevant log files

N/A

Additional context

N/A

Environment

Software version used and hardware type if relevant, e.g.:

OPNsense 25.7.9 (amd64).

[Monviech]

Its the API for this component:

https://docs.opnsense.org/manual/firewall_automation.html

[dca00]

This is what the documentation says:

If this is not accurate, it should be corrected or re-phrased so that it is easier to comprehend what is referring to what.

[AdSchellevis]

Well just wait for your pull request with suggestions then….

[dca00]

Being unable to comprehend it, I won't be able to make any suggestions. I have no idea what you mean by almost anything on that page. For example, the rule toggle API call lists UUID and enable as two distinct parameters, whereas your Python example does not seem to pass them but has an extra item on the URL path:

r = requests.post("%s/api/firewall/filter/toggleRule/%s/0" % (remote_uri, rule_uuid), auth=(api_key, api_secret), verify=False

From Google, it seems that I am not the only one who is having hell of a hard time understanding the API documentation. Nothing that I tried worked, including the syntax in the example above. This is a Schrödinger API, essentially: impossible to figure out, absent prior knowledge.

[dca00]

I created an automation rule with the same description as in the Python example:

I issued the same call as in the example. The result is empty:

With or without the extra parameters:

Should those extra parameters be documented, by the way? Also noticed that you use searchRule method, whereas the documentation shows search_rule. Care to elaborate more about which is the correct/preferred? Do both spellings, with and without the underscore, do the same? Your users will be confused by these inconsistencies.