API Disappointment story - or: how to export the WAN IP

[part_time_nerd]

Hi all,

I just wanted to share with you the experiences I had trying to use the API in 17.1

I am a fresh opnsense user and I have my own, homegrown "dyndns" solution which includes a challenge-response authentication that I could not easily integrate with the mechaisms in the opnsense GUI. So I needed to extract the WAN ip from the router for a custom script. I found the API section in the dev wiki and it seemed the perfect tool for the task.

However, after reading the nice examples I began searching for the API documentation ... and did not find any. I could not believe that this should be it so I kept searching harder, but an hour later I had realized that the API docs are basically UTSL - so I cloned the source and grepped. Then I made a user for API access.
Since the API sections I had discovered did not intuitively match most of the rights that can be granted in the UI and I got lots of "Authentication error"s, I soon WTFed and granted all rights to it for the sake of exploration. Goodbye security. I did, however, not find a single API call that would allow me to simply extract the currently used WAN IP. After a lot of trying and cursing and at least three hours wasted, I disabled the API user, went to the shell and created a simple cronjob, that greps the WAN IP from ifconfig and dumps it into a file named "ip" in the web root. Done in 10 minutes.

Base line:

Trying to use the API turned out to be a very frustrating endeavour for me, mostly because the wiki page made it look like being a lot more usable than it actually is.
If you have an API but no documentation whatsoever, please mention that in a prominent place. Also the fact that by far not every part of opnsense has API support should be mentioned somewhere. If possible, the API should be extended in a way that authentication errors include information about which rights are missing to use a certain call.

Please note that this post is meant to be constructive criticism and not a personal insult. I am aware that this is open source and I am not entitled to demand anything. I thought, however, you might be interested in my experience.

[franco]

Hi there,

The API is currently implemented for traffic shaping, captive portal, netflow and health reporting, firmware updates, cron, web proxy and intrusion detection. I believe there is also a smaller API for the dashboard widgets, but it uses a different approach tailored for actual widget use cases.

It's true that the API isn't documented in detail. We decided to look into API doc generation tools and the only key element is missing time. The official docs also could use more details on what currently works and what does not. Sorry for the trouble here.

What you want to do isn't easily possible, probably won't be for a while longer. Our next and most valuable target also according to users is the management of firewall rules.


Cheers,
Franco