Zum Inhalt springen
HabitatOSby GeckioDokumentation

Dokumentation durchsuchen

Suche in Titeln und vollständigen Artikeln

    App öffnen
    Alle Themen

    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.

    Stand: 2 Min. Lesezeit

    Noch eine Frage? Schreib uns oder öffne die Fehlerhilfe.