Skip to content

Dynamic interfaces

A dynamic interface is a user-defined endpoint with its own data table. When you create one you choose:

  • an interface_url (for example /weather_station), which becomes the address devices push data to: https://spoilerinterface.com/interface/dynamic/interface/weather_station;
  • a table_name (for example weather_station_data), the database table that stores the rows;
  • a list of fields, which become the table columns.

Every interface automatically gets an epoch_time (Integer) field, which is used to order the rows. If a pushed row does not include epoch_time, the server time is used.

Naming rules:

Item Rule
interface_url Must start with / and contain only letters, digits, _ and / (regex ^/[\w/]*$). Must be unique across the platform. Use a single path segment (e.g. /weather_station): the data endpoints take the URL as one path parameter, so URLs containing a second / cannot be reached.
table_name Must be a plain identifier: starts with a letter or _, then letters, digits or _, max 63 characters. Must not already exist.
field_name Same rule as table_name. id is reserved.
field_type One of Integer, String, Text, Boolean.

Field object (FieldModel):

Field name Description Type
field_name Column name str
field_type Integer, String, Text or Boolean str
trendable Whether the dashboard should plot this field as a trend bool
required When true, data pushes that omit this field are rejected bool

All management endpoints return the standard {"success": ...} / {"failed": ...} envelope. See also Alarms (device_type dynamic / interface) and MQTT.

Add dynamic interface

POST/dynamic

Creates a new dynamic interface and its data table

Request

Auth: api_key (query param or cookie) · Content-type: application/json

Request body:

The request body must be a JSON object. interface_url, interface_token and update_period may alternatively be sent as query parameters; interface_description, table_name and fields must be in the JSON body. The request fails if the account has reached its device limit.

Field name Description Type
interface_url URL of the interface, starting with / (see naming rules above) str
interface_description Human readable description str
table_name Name of the table that stores the rows str
fields Array of field objects (see FieldModel above) arr
update_period Expected update interval in seconds. If no data is received within this period the interface is regarded as offline and a status email is sent (when notifications are enabled) int
interface_token [Optional] Token for the interface. A random token is generated if not specified str

Request example:

{
    "interface_url": "/weather_station",
    "interface_description": "Rooftop weather station",
    "table_name": "weather_station_data",
    "update_period": 300,
    "fields": [
        {"field_name": "temperature", "field_type": "Integer", "trendable": true, "required": true},
        {"field_name": "condition", "field_type": "String", "trendable": false, "required": false},
        {"field_name": "raining", "field_type": "Boolean", "trendable": false, "required": false}
    ]
}

Response

{
    "success": {
        "interface_id": 1716549872345,
        "interface_url": "/weather_station"
    }
}

Field description

Field name Description Type
interface_id ID of the new interface. Use it to edit or delete the interface int
interface_url URL of the interface str

Common failures: Missing field: <name>, Invalid field: interface_url. URL should start with '/', Failed to create interface. URL already exists., Failed to create table. Table name already exists., Failed to validate the data type for: <field_name>, Maximum number of devices reached. Please upgrade your account.

Edit dynamic interface

PUT/dynamic

Updates the settings and/or field list of an existing dynamic interface

Request

Auth: api_key (query param or cookie) · Content-type: application/json

Request body:

The request body must be a JSON object. Only interface_id is required; every other field is updated only when supplied.

When fields is supplied it replaces the whole field list: columns that are no longer listed are dropped from the table (their data is lost) and new fields are added as columns. epoch_time is always kept.

Field name Description Type
interface_id ID of the interface to edit int
interface_url [Optional] New URL (same rules as when adding; must be unique) str
interface_description [Optional] New description str
interface_token [Optional] New token str
update_period [Optional] New update period in seconds int
fields [Optional] Complete new list of field objects arr
notification_users [Optional] JSON-encoded string holding an array of extra notification recipients (see below) str
notification_enabled [Optional] Only true is applied; use Notifications to disable bool
whatsapp_enabled [Optional] Only true is applied bool
sms_enabled [Optional] Only true is applied bool

Each notification_users entry is an object with email (required), name, threshold_alerts, status_alerts, sms_alerts, whatsapp_alerts (booleans) and mobile_number (required when SMS or WhatsApp alerts are on; must start with + and the country code).

Request example:

{
    "interface_id": 1716549872345,
    "interface_description": "Rooftop weather station (north)",
    "update_period": 600,
    "notification_users": "[{\"name\": \"Ops\", \"email\": \"user@example.com\", \"status_alerts\": true, \"threshold_alerts\": true}]"
}

Response

{
    "success": "Successfully updated the interface."
}

List dynamic interfaces

GET/dynamic

Returns all dynamic interfaces owned by the user

Request

Auth: api_key (query param or cookie)

Request body:

None

Request example:

https://spoilerinterface.com/interface/dynamic?api_key=8f14e45fceea167a5a36dedd4bea2543

Response

{
    "success": [
        {
            "interface_url": "/weather_station",
            "interface_id": 1716549872345,
            "interface_status": "Online",
            "interface_description": "Rooftop weather station",
            "table_name": "weather_station_data",
            "interface_token": "c9f0f895fb98ab9159f51fd0297e236d",
            "interface_details": null,
            "update_period": 300,
            "last_modified": 1716553472,
            "notification_enabled": true,
            "whatsapp_enabled": null,
            "sms_enabled": null,
            "notification_users": [],
            "alarms": [],
            "fields": [
                {"field_name": "temperature", "field_type": "Integer", "trendable": true, "required": true},
                {"field_name": "condition", "field_type": "String", "trendable": false, "required": false},
                {"field_name": "epoch_time", "field_type": "Integer", "trendable": false, "required": false}
            ]
        }
    ]
}

Field description

Field name Description Type
interface_status Online if data was received within update_period, otherwise Offline str
last_modified Time of the last data push (epoch seconds, shifted by the user's time offset) int
alarms Alarms attached to the interface (see Alarms) arr
fields Field definitions, including the automatic epoch_time field arr
notification_users Extra notification recipients arr

Delete dynamic interface

DELETE/dynamic

Deletes a dynamic interface and drops its data table

Request

Auth: api_key (query param or cookie) · Content-type: application/json

Request body:

Field name Description Type
interface_id ID of the interface to delete int

Request example:

{
    "interface_id": 1716549872345
}

Response

{
    "success": "Successfully deleted the interface."
}

Note: All stored rows are permanently deleted together with the table.

Get interface data

GET/dynamic/interface/{interface_url}

Returns the latest data rows stored for a dynamic interface

Request

Auth: api_key (query param or cookie)

Request body:

None. {interface_url} is the interface URL without the leading / (e.g. weather_station).

The most recent 600 rows are returned, sorted oldest-first. epoch_time is converted to a date-time string in the user's time offset.

Request example:

https://spoilerinterface.com/interface/dynamic/interface/weather_station?api_key=8f14e45fceea167a5a36dedd4bea2543

Response

{
    "success": [
        {
            "id": 41,
            "temperature": 22,
            "condition": "Sunny",
            "raining": false,
            "epoch_time": "2024-05-24T12:10:00"
        },
        {
            "id": 42,
            "temperature": 23,
            "condition": "Sunny",
            "raining": false,
            "epoch_time": "2024-05-24T12:15:00"
        }
    ]
}

Field description

Each row contains an auto-increment id, one key per defined field and epoch_time.

Push interface data

POST/dynamic/interface/{interface_url}

Adds a new data row to a dynamic interface (used by devices)

Request

Auth: None (the interface URL identifies the interface) · Content-type: application/json

Request body:

The request body must be a JSON object whose keys are the interface's field names. Keys that are not defined fields are ignored. Every field marked required: true must be present (and not null).

Field name Description Type
<field_name> Value for each defined field int / str / bool
epoch_time [Optional] Time of the reading in epoch seconds. Defaults to the server time int

Rate limit: pushes are limited by the owner's account tier. If the previous push was too recent the row is rejected.

Account type Minimum time between pushes
1 (Basic) or unknown 59 s
2 - 4 30 s
5 (Enterprise) 1 s

Request example:

POST https://spoilerinterface.com/interface/dynamic/interface/weather_station

{
    "temperature": 23,
    "condition": "Sunny",
    "raining": false
}

Response

{
    "success": "success"
}

Rate limited response:

{
    "failed": {
        "message": "Please wait for the update period to lapse. Remaining time is: 12",
        "remaining_time_sec": 12
    }
}

Other failures: Interface not found., Failed to update interface. Missing required field: <field_name>, Failed to get payload. Ensure that the payload is a correct object. ...

Each successful push updates the interface's last_modified time (used for the Online/Offline status) and counts as one API call for the owner.