The API service exists for communication between service containers and to support external requests from the web front end or CLI tools.
The internal APIs run over unix sockets and rely on filesystem namespaces for authentication. Currently there are a few internal APIs exposed to containers over unix sockets:
- Support for wifid service accepting stations
- Setting up dynamic firewall rules for DHCP clients
- Support for wireguard peers
A list of curated plugins is available here
API plugins let other docker services expose web APIs with unix sockets that are relayed with a reverse proxy.
To add a new plugin update
configs/base/api.json or use the UI to enable it.
If the plugin should be started by SPR, then make sure that the compose path is added to the whitelist.
To do so, update
Example dyndns plugin
"Name": "dyndns extension",
You can also talk to the spr api directly to list/add/delete plugins - see the api documentation for plugins.
Or in the UI navigate to System -> Plugins. Note, SPR for now will not accept arbitrary
compose file paths. Instead, update
configs/base/custom_compose_paths.json with the relative path
to the plugin.
Query the http API
It is recommended to create a token to talk to the API (more info about authentication here). In the Admin UI, click Add Auth Token under System -> Auth. Use this token for authorization:
curl -s -H "Authorization: Bearer $TOKEN" 192.168.2.1/plugins
Query a plugin API
If developing a plugin on the same host as spr you can talk to a specific plugins unix socket.
Example - talk to db service to get stats:
sudo curl -s --unix-socket ./state/plugins/db/socket 0/stats
SPR Event Bus
Clients connect to
/state/api/eventbus.sock, either subscribing to a topic or publishing events for other clients to handle.
The sprbus command line tool can be used to inspect live events:
See the github repository for more examples.
Read more about SPRbus