Skip to main content

API Overview

View the OpenAPI Documentation here

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:

⇨ View the code

API Plugins​

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 configs/base/custom_compose_paths.json

Example dyndns plugin

{
  "Plugins": [
    {
      "Name": "dyndns extension",
      "URI": "dyndns",
      "UnixPath": "/state/plugins/dyndns/dyndns_plugin",
      "Enabled": true,
      "ComposeFilePath": "dyndns/docker-compose.yml"            
    }
  ]
}

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:

export TOKEN="paste-token-here"
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:

pwd
/home/spr/super
sudo curl -s --unix-socket ./state/plugins/db/socket 0/stats

SPR Event Bus​

sprbus is an event bus for publishing and subscribing to events. The server routing messages between services is setup in the api service.

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:

sprbus

See the github repository for more examples.

Read more about SPRbus