newbie questions about API maturity & architecture

[ivar]

I'm intrigued by the ability to use an API to configure Opnsense and am thinking how it might fit in with an idea of mine. Unfortunately, the documentation for the API does not include a link to where the current API is defined.
The API howto at https://docs.opnsense.org/development/how-tos/api.html is a good start but where can I find out what API endpoints we can use now and what is still being developed?
 

[fabian]

The API endpoints are used by the Web GUI itself and you can find them via git because they are in the Api directory of any controller directory. You just have to look for methods ending with Action.

[franco]

The API is stable as we use it in the GUI pages. However, not all pages have an API and we are not yet able to generate API docs from the code.

These are our core.git API endpoints:

$ git ls-files | grep "/Api/"
src/opnsense/mvc/app/controllers/OPNsense/CaptivePortal/Api/AccessController.php
src/opnsense/mvc/app/controllers/OPNsense/CaptivePortal/Api/ServiceController.php
src/opnsense/mvc/app/controllers/OPNsense/CaptivePortal/Api/SessionController.php
src/opnsense/mvc/app/controllers/OPNsense/CaptivePortal/Api/SettingsController.php
src/opnsense/mvc/app/controllers/OPNsense/CaptivePortal/Api/VoucherController.php
src/opnsense/mvc/app/controllers/OPNsense/Core/Api/FirmwareController.php
src/opnsense/mvc/app/controllers/OPNsense/Core/Api/MenuController.php
src/opnsense/mvc/app/controllers/OPNsense/Cron/Api/ServiceController.php
src/opnsense/mvc/app/controllers/OPNsense/Cron/Api/SettingsController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/ActivityController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/DnsController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/FirewallController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/InterfaceController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/NetflowController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/NetworkinsightController.php
src/opnsense/mvc/app/controllers/OPNsense/Diagnostics/Api/SystemhealthController.php
src/opnsense/mvc/app/controllers/OPNsense/IDS/Api/ServiceController.php
src/opnsense/mvc/app/controllers/OPNsense/IDS/Api/SettingsController.php
src/opnsense/mvc/app/controllers/OPNsense/Proxy/Api/ServiceController.php
src/opnsense/mvc/app/controllers/OPNsense/Proxy/Api/SettingsController.php
src/opnsense/mvc/app/controllers/OPNsense/Routes/Api/RoutesController.php
src/opnsense/mvc/app/controllers/OPNsense/TrafficShaper/Api/ServiceController.php
src/opnsense/mvc/app/controllers/OPNsense/TrafficShaper/Api/SettingsController.php
src/opnsense/mvc/app/controllers/OPNsense/Unbound/Api/DiagnosticsController.php

And here are the plugin.git API endpoints:

$ git ls-files | grep "/Api/"
benchmarks/iperf/src/opnsense/mvc/app/controllers/OPNsense/iperf/Api/InstanceController.php
benchmarks/iperf/src/opnsense/mvc/app/controllers/OPNsense/iperf/Api/ServiceController.php
databases/redis/src/opnsense/mvc/app/controllers/OPNsense/Redis/Api/ServiceController.php
databases/redis/src/opnsense/mvc/app/controllers/OPNsense/Redis/Api/SettingsController.php
devel/helloworld/src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/Api/ServiceController.php
devel/helloworld/src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/Api/SettingsController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/AntispamController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/DomainController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/GeneralController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/RecipientController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/SenderController.php
mail/postfix/src/opnsense/mvc/app/controllers/OPNsense/Postfix/Api/ServiceController.php
mail/rspamd/src/opnsense/mvc/app/controllers/OPNsense/Rspamd/Api/ServiceController.php
mail/rspamd/src/opnsense/mvc/app/controllers/OPNsense/Rspamd/Api/SettingsController.php
net-mgmt/collectd/src/opnsense/mvc/app/controllers/OPNsense/Collectd/Api/GeneralController.php
net-mgmt/collectd/src/opnsense/mvc/app/controllers/OPNsense/Collectd/Api/ServiceController.php
net-mgmt/lldpd/src/opnsense/mvc/app/controllers/OPNsense/Lldpd/Api/GeneralController.php
net-mgmt/lldpd/src/opnsense/mvc/app/controllers/OPNsense/Lldpd/Api/ServiceController.php
net-mgmt/telegraf/src/opnsense/mvc/app/controllers/OPNsense/Telegraf/Api/GeneralController.php
net-mgmt/telegraf/src/opnsense/mvc/app/controllers/OPNsense/Telegraf/Api/InputController.php
net-mgmt/telegraf/src/opnsense/mvc/app/controllers/OPNsense/Telegraf/Api/OutputController.php
net-mgmt/telegraf/src/opnsense/mvc/app/controllers/OPNsense/Telegraf/Api/ServiceController.php
net-mgmt/zabbix-agent/src/opnsense/mvc/app/controllers/OPNsense/ZabbixAgent/Api/ServiceController.php
net-mgmt/zabbix-agent/src/opnsense/mvc/app/controllers/OPNsense/ZabbixAgent/Api/SettingsController.php
net-mgmt/zabbix-proxy/src/opnsense/mvc/app/controllers/OPNsense/Zabbixproxy/Api/GeneralController.php
net-mgmt/zabbix-proxy/src/opnsense/mvc/app/controllers/OPNsense/Zabbixproxy/Api/ServiceController.php
net/arp-scan/src/opnsense/mvc/app/controllers/OPNsense/ARPscanner/Api/ServiceController.php
net/arp-scan/src/opnsense/mvc/app/controllers/OPNsense/ARPscanner/Api/SettingsController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/ClientController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/EapController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/GeneralController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/LdapController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/ServiceController.php
net/freeradius/src/opnsense/mvc/app/controllers/OPNsense/Freeradius/Api/UserController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/BgpController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/DiagnosticsController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/GeneralController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/Ospf6settingsController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/OspfsettingsController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/RipController.php
net/frr/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/ServiceController.php
net/ftp-proxy/src/opnsense/mvc/app/controllers/OPNsense/FtpProxy/Api/ServiceController.php
net/ftp-proxy/src/opnsense/mvc/app/controllers/OPNsense/FtpProxy/Api/SettingsController.php
net/haproxy/src/opnsense/mvc/app/controllers/OPNsense/HAProxy/Api/ServiceController.php
net/haproxy/src/opnsense/mvc/app/controllers/OPNsense/HAProxy/Api/SettingsController.php
net/haproxy/src/opnsense/mvc/app/controllers/OPNsense/HAProxy/Api/StatisticsController.php
net/mdns-repeater/src/opnsense/mvc/app/controllers/OPNsense/MDNSRepeater/Api/ServiceController.php
net/mdns-repeater/src/opnsense/mvc/app/controllers/OPNsense/MDNSRepeater/Api/SettingsController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/BgpController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/DiagnosticsController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/GeneralController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/Ospf6settingsController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/OspfsettingsController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/RipController.php
net/quagga/src/opnsense/mvc/app/controllers/OPNsense/Quagga/Api/ServiceController.php
net/siproxd/src/opnsense/mvc/app/controllers/OPNsense/Siproxd/Api/DomainController.php
net/siproxd/src/opnsense/mvc/app/controllers/OPNsense/Siproxd/Api/GeneralController.php
net/siproxd/src/opnsense/mvc/app/controllers/OPNsense/Siproxd/Api/ServiceController.php
net/siproxd/src/opnsense/mvc/app/controllers/OPNsense/Siproxd/Api/UserController.php
net/zerotier/src/opnsense/mvc/app/controllers/OPNsense/Zerotier/Api/NetworkController.php
net/zerotier/src/opnsense/mvc/app/controllers/OPNsense/Zerotier/Api/SettingsController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/AccountsController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/ActionsController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/CertificatesController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/ServiceController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/SettingsController.php
security/acme-client/src/opnsense/mvc/app/controllers/OPNsense/AcmeClient/Api/ValidationsController.php
security/clamav/src/opnsense/mvc/app/controllers/OPNsense/ClamAV/Api/GeneralController.php
security/clamav/src/opnsense/mvc/app/controllers/OPNsense/ClamAV/Api/ServiceController.php
security/tinc/src/opnsense/mvc/app/controllers/OPNsense/Tinc/Api/ServiceController.php
security/tinc/src/opnsense/mvc/app/controllers/OPNsense/Tinc/Api/SettingsController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/ExitaclController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/GeneralController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/HiddenserviceController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/HiddenserviceaclController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/RelayController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/ServiceController.php
security/tor/src/opnsense/mvc/app/controllers/OPNsense/Tor/Api/SocksaclController.php
sysutils/monit/src/opnsense/mvc/app/controllers/OPNsense/Monit/Api/ServiceController.php
sysutils/monit/src/opnsense/mvc/app/controllers/OPNsense/Monit/Api/SettingsController.php
sysutils/monit/src/opnsense/mvc/app/controllers/OPNsense/Monit/Api/StatusController.php
sysutils/nut/src/opnsense/mvc/app/controllers/OPNsense/Nut/Api/ServiceController.php
sysutils/nut/src/opnsense/mvc/app/controllers/OPNsense/Nut/Api/SettingsController.php
www/c-icap/src/opnsense/mvc/app/controllers/OPNsense/CICAP/Api/AntivirusController.php
www/c-icap/src/opnsense/mvc/app/controllers/OPNsense/CICAP/Api/GeneralController.php
www/c-icap/src/opnsense/mvc/app/controllers/OPNsense/CICAP/Api/ServiceController.php
www/web-proxy-sso/src/opnsense/mvc/app/controllers/OPNsense/ProxySSO/Api/ServiceController.php
www/web-proxy-sso/src/opnsense/mvc/app/controllers/OPNsense/ProxySSO/Api/SettingsController.php
www/web-proxy-useracl/src/opnsense/mvc/app/controllers/OPNsense/ProxyUserACL/Api/SettingsController.php

As you can see, almost all plugins have been written to use an API already.


Cheers,
Franco