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 exampleweather_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¶
/dynamicCreates 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¶
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¶
/dynamicUpdates 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¶
List dynamic interfaces¶
/dynamicReturns 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¶
/dynamicDeletes 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:
Response¶
Note: All stored rows are permanently deleted together with the table.
Get interface data¶
/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¶
/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
Response¶
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.