Перейти к содержанию

API Overview

REST API контроллера AWDC. Все эндпоинты под префиксом /api/, формат тела — JSON, аутентификация — HTTP Basic.

Формальная спецификация: ../openapi.yaml.

Группы

Файл Группа Содержит
auth.md Аутентификация /api/auth/*
dosator.md Дозаторы /api/dosator/*, /api/statistics*
diagnostics.md Диагностика /api/diag/*, /api/status
network.md Сеть /api/sta/*, /api/ap/*, /api/net/*
integrations.md Интеграции /api/integration/{mail,telegram,maxbot}/*
system.md Система /api/system/*, /api/ota/*

Аутентификация

Схема: HTTP Basic Auth. В каждом запросе передаётся заголовок:

Authorization: Basic <base64(username:password)>

Учётные записи (захардкожены, всего две):

Username Default password Роль
admin admin123 ADMIN
duty duty123 DUTY

Пароли хранятся в NVS namespace auth (см. ../nvs-reference.md) и меняются через POST /api/auth/change_password.

Ролевая модель

NONE  <  USER  <  DUTY  <  ADMIN
  • USER — не реальный логин, а порог «любой авторизованный». Эндпоинты с требованием Role::USER доступны всем (admin и duty).
  • DUTY — оператор: чтение всего + управление дозаторами.
  • ADMIN — конфигурация всего, OTA, backup/restore, change_password для любого пользователя.

Каждый эндпоинт ниже помечен минимальной требуемой ролью.

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

curl -u admin:admin123 http://awdc.local/api/auth/me

curl -u admin:admin123 -X POST \
     -H "Content-Type: application/json" \
     -d '{"ch":0,"proportion":25}' \
     http://awdc.local/api/dosator/config

Формат ответов

Успех

HTTP 200 OK с JSON-телом. Структура зависит от эндпоинта. Если эндпоинт ничего не возвращает (action-only) — обычно:

{"success": true}

Ошибки

Используются два формата (исторически):

Короткий: 

{"error": "Unauthorized"}

Развёрнутый (action-эндпоинты): 

{"success": false, "message": "proportion must be 0..99"}

Коды

HTTP Когда
200 Успех
204 Успех, тела нет (некоторые DELETE/POST без ответа)
400 Bad Request: invalid JSON, missing fields, out-of-range значения
401 Unauthorized: нет заголовка Authorization, или неверный пароль
403 Forbidden: авторизация прошла, но роль ниже требуемой
404 Endpoint не найден
413 Payload Too Large: JSON body больше MAX_JSON_BODY_SIZE
500 Внутренняя ошибка (см. лог)

Заголовки

  • Content-Type: application/json — обязателен для POST с телом.
  • Content-Type: application/json; charset=utf-8 — в ответах.

Хост и порт

Web-сервер на порту 80. Адрес устройства:

  • AP-режим: http://192.168.4.1/ (когда нет подключения к STA)
  • STA-режим: IP, выданный DHCP (или статический из sta-config)
  • mDNS: http://awdc.local/ — если в сети есть резолвер (Bonjour на macOS/iOS/Windows; на Linux нужен avahi-daemon)

Текущий IP и режим — GET /api/status (без auth) или GET /api/net/status.

Конвенции запросов

  • Каналы дозаторов: индексация ch ∈ {0, 1, 2} (НЕ {1, 2, 3}).
  • Время: uptime в миллисекундах, runtime каналов в секундах, ISO-8601 для абсолютного времени (если NTP синхронизирован).
  • Размеры: байты — целые, без префиксов.
  • Пароли: в password поле в plaintext. TLS не используется — передавать с осторожностью (только через локальную сеть).
  • Секреты в GET /config: возвращаются как строка "***", если поле заполнено в NVS, или "" если пусто. При сохранении присланный "***" означает «не менять».