Schnittstellen
Die Web- und mobile App nutzen das HabitatOS-Backend. Die Schnittstellen sind Bestandteil des Prototyps und noch kein versionierter öffentlicher API-Vertrag. Eine vollständige OpenAPI-Spezifikation und freigegebene Integrationsbeispiele stehen aus.
| Bereich | Pfade |
|---|---|
| E-Mail-Link anfordern und bestätigen | /api/auth/email, /api/auth/email/verify |
| Sitzung / Profil | /api/auth/session |
| Terrarien | /api/terraria, /api/terraria/[id] |
| Aktivitäten | /api/terraria/[id]/activity |
| Geräte | /api/devices, /api/devices/[id] |
| Status und Aktionen | /api/devices/[id]/state, /api/devices/[id]/toggle |
| Arten | /api/species, /api/species/[id] |
| Pläne | /api/programs, /api/programs/[id], /api/programs/activate, /api/programs/templates |
| Regeldefinitionen | /api/automations, /api/automations/[id] |
[id] steht für die jeweilige Datensatz-ID. Die Übersicht ist eine Einordnung, keine Zusage, dass jede HTTP-Methode an jedem Pfad unterstützt wird.
Authentifizierung und Antworten#
Im Web fordert POST /api/auth/email mit E-Mail-Adresse und optionalem Namen einen Anmeldelink an. POST /api/auth/email/verify bestätigt den einmaligen Token ausdrücklich. Beide Endpunkte sind für die Anmeldung vorgesehen; sie benötigen noch keine bestehende Sitzung.
Kontobezogene Aufrufe verwenden anschließend eine signierte Sitzung. Ein selbst gesetzter x-user-id-Header ist kein Zugangsnachweis. Schreibaufrufe unterliegen zusätzlich einer Origin-Prüfung.
Die gemeinsamen Antworthelfer verwenden diese Struktur; ein erfolgreicher Leseaufruf kann zum Beispiel eine leere Liste liefern:
{"success":true,"data":[],"error":null}
Fehler enthalten success: false, data: null und ein Fehlerobjekt mit code und message. Listen können Pagination unter meta.pagination liefern. Antworten mit HTTP 204 haben keinen JSON-Body. Einzelne öffentliche oder administrative Endpunkte können abweichende Verträge haben.
Häufige Fehlercodes#
| Code | Bedeutung |
|---|---|
UNAUTHORIZED |
Keine gültige Sitzung |
VALIDATION_ERROR |
Eingabe passt nicht zum erwarteten Schema |
UNSUPPORTED_CAPABILITY |
Aktion wird für dieses Gerät nicht angeboten |
DEVICE_OFFLINE |
Geräteanbindung nicht erreichbar |
AUTH_FAILED |
Gerätezugang abgelehnt |
DESTINATION_NOT_ALLOWED |
Zieladresse nicht freigegeben |
INVALID_RESPONSE |
Geräteantwort nicht verwertbar |
DEVICE_TIMEOUT |
Zeitlimit der Geräteanfrage überschritten |
Die Betreiberdiagnose ist kein öffentlicher Automationsdienst. Zugangsdaten zu Geräten oder Verwaltung gehören nicht in Integrationsbeispiele. Konkrete Request-Schemata, Versionsregeln und Authentifizierungsbeispiele werden vor einer API-Veröffentlichung ergänzt.