Skip to main content
SPRby Supernetworks

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.

Authenticated plugin proxy​

Plugin UIs are sandboxed by default and do not receive the signed-in user's SPR credential. When an authenticated user opens a plugin UI, SPR issues a short-lived plugin session token scoped exactly to that plugin's /plugins/<URI> route. Requests bearing the token can reach that plugin and its child paths, but cannot reach regular SPR API routes, other plugins, token management, or WebSockets.

The token authenticates the request to the SPR reverse proxy. SPR removes the Authorization header before forwarding the request to the plugin's Unix socket, so the plugin backend never receives the browser credential. Sessions are held in memory, expire automatically, and are rekeyed through the authenticated parent UI when an API restart invalidates them.

If a plugin backend must initiate calls to other SPR API routes, it must declare a separate InstallTokenPath and the minimum necessary ScopedPaths. Backends that do not call the SPR API should not request an install token. Prefer :r scopes and grant :rw only where modification is required.

Legacy plugins may set SandboxedUI: false, which gives their same-origin UI access to the signed-in user's SPR API credentials. SPR warns users before opening these UIs. New plugins should use the sandboxed default.

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