API сервиса

Содержание

• POST /init — регистрация и конфигурация
• POST /{token}/data — отправка показаний
• GET /{tokenOrUrl}/data — последние данные
• GET|PUT /{token}/state — флаги состояния
• GET|PUT /{token}/info — публичная информация
• GET /{token}/show — история
• GET /list — список публичных устройств
• API v2 (REST) — параллельный контракт
• Формат данных датчиков
• Семантика state1–state8
• Служебное и realtime

POST /init

Регистрация нового устройства или получение актуальной конфигурации. Рекомендуется вызывать при каждом старте (как в прошивке TWL). Тело запроса — JSON. Обязателен только mac.

Пример запроса

curl -X POST https://bigapi.ru/init \
  -H "Content-Type: application/json" \
  -d '{
    "mac": "F0:98:9D:1C:93:F6",
    "deviceId": "12345678",
    "model": "VeloCliMat",
    "revision": "second",
    "firmware": "6.2",
    "ssid": "HomeWiFi"
  }'

Пример ответа (200 или 201 при создании)

{
  "token": "PA12-45DD-XJR6-AV31",
  "time": 1708978792,
  "state1": "100",
  "state2": "",
  "state3": "",
  "state4": "",
  "state5": "",
  "state6": "",
  "state7": "",
  "state8": "",
  "created": true
}

POST /{token}/data

Приём показаний датчиков. Ключи внутри data — типы сенсоров, уже заведённые на сервере (например BME280, HTU21, SHT31). Неизвестный тип игнорируется.

curl -X POST https://bigapi.ru/PA12-45DD-XJR6-AV31/data \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "BME280": {
        "temperature": "12.4",
        "humidity": "67.1",
        "pressure": "754.2"
      },
      "HTU21": {
        "temperature": "23.1",
        "humidity": "41.5"
      }
    }
  }'

Ответ при успехе: пустой JSON-объект {}.

GET /{tokenOrUrl}/data

Последняя запись с устройства. В path можно передать либо секретный token, либо публичный url. Поле data возвращается как массив значений (порядок соответствует порядку полей при отправке).

curl https://bigapi.ru/center/data

{
  "data": ["12.4", "67.1", "754.2"],
  "time": "14:32:01"
}

GET PUT /{token}/state

Чтение и обновление восьми строковых флагов state1–state8. PUT принимает JSON или form-urlencoded. В ответе PUT — массив номеров изменённых слотов.

curl https://bigapi.ru/PA12-45DD-XJR6-AV31/state

{
  "state1": "100",
  "state2": "center",
  "state3": "60000",
  "state4": "Двор",
  "state5": "",
  "state6": "",
  "state7": "",
  "state8": ""
}

curl -X PUT https://bigapi.ru/PA12-45DD-XJR6-AV31/state \
  -H "Content-Type: application/json" \
  -d '{
    "state1": "80",
    "state2": "center",
    "state3": "60000",
    "state4": "Двор"
  }'
# ответ, например: [1, 4]

GET PUT /{token}/info

Публичные метаданные устройства. PUT принимает JSON или form-urlencoded.

curl -X PUT https://bigapi.ru/PA12-45DD-XJR6-AV31/info \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Балкон",
    "location": "Санкт-Петербург",
    "owner": "demo",
    "lat": "59.93",
    "lon": "30.33",
    "device_model": "VeloCliMat second 6.2",
    "url": "balcony"
  }'

GET /{token}/show

Последние 100 записей с устройства (по убыванию времени).

curl https://bigapi.ru/PA12-45DD-XJR6-AV31/show

[
  {
    "sensorType": "BME280",
    "data": ["12.4", "67.1", "754.2"],
    "time": "2024-02-26 14:32:01"
  }
]

GET /list

Публичные url устройств с флагами publish и active.

curl https://bigapi.ru/list

{
  "data": ["center", "balcony", "yard"]
}

API v2 (REST)

Параллельный контракт под префиксом /api/v2. Тела ответов те же, что у v1; пути и HTTP-коды — в REST-стиле. Эндпоинты v1 (/init, /{token}/…, /sputnik) не меняются и не deprecated.

Для операций устройства передавайте Authorization: Bearer {token} на маршрутах /api/v2/devices/me/…. Публичное чтение идёт по slug url.

curl -X POST https://bigapi.ru/api/v2/devices \
  -H "Content-Type: application/json" \
  -d '{"mac":"F0:98:9D:1C:93:F6","url":"center"}'

curl -X POST https://bigapi.ru/api/v2/devices/me/data \
  -H "Authorization: Bearer PA12-45DD-XJR6-AV31" \
  -H "Content-Type: application/json" \
  -d '{"data":{"BME280":{"temperature":"12.4","humidity":"67.1","pressure":"754.2"}}}'

curl https://bigapi.ru/api/v2/devices/center/data

curl https://bigapi.ru/api/v2/devices/nearby

Формат данных датчиков

Как в прошивке TWL: объект data содержит именованные блоки по типу сенсора. При сохранении значения упорядочиваются в массив — поэтому при GET …/data монитор читает data[0], data[1], …

{
  "data": {
    "BME280": {
      "temperature": "12.4",
      "humidity": "67.1",
      "pressure": "754.2"
    },
    "HTU21": {
      "temperature": "23.1",
      "humidity": "41.5"
    },
    "SHT31": {
      "temperature": "22.8",
      "humidity": "43.0"
    }
  }
}

Семантика state1–state8 (прошивка TWL)

Слоты произвольные строки на стороне API. В TWL они используются так:

Служебное и realtime

• GET /sputnik — упрощённый снимок фиксированного устройства (для сторонних клиентов вроде Garmin data field). Не универсальный публичный API. В v2: GET /api/v2/devices/nearby.
• После POST /{token}/data сервер публикует событие Mercure в топики https://bigapi.ru/global и https://bigapi.ru/{url} (карта и страница устройства подписаны на обновления).