SynGrow API Dokumentation

Integrieren Sie Ihre IoT-Geräte und Anwendungen nahtlos mit der SynGrow-Plattform.

Einführung

Die SynGrow API ermöglicht es Ihnen, Sensordaten zu senden, Grow-Informationen abzurufen und Ihre IoT-Geräte vollständig in unser Ökosystem zu integrieren. Unsere RESTful API unterstützt JSON-Formate und bietet Echtzeit-Updates über Webhooks.

REST APIJSONWebhooksReal-time

Authentifizierung

Sichern Sie Ihre API-Aufrufe mit API-Schlüsseln

Alle API-Anfragen müssen mit einem gültigen API-Schlüssel authentifiziert werden. Sie können API-Schlüssel in Ihrem Dashboard unter Einstellungen → API-Schlüssel erstellen.

Header-Authentifizierung

Fügen Sie Ihren API-Schlüssel im Authorization-Header ein:

Authorization: Bearer YOUR_API_KEY

API Endpunkte

Geräte-Endpunkte

GET/api/v1/devices

Listet alle Ihre registrierten Geräte auf.

curl -X GET https://api.syngrow.com/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/devices

Registriert ein neues IoT-Gerät.

curl -X POST https://api.syngrow.com/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ESP32 Sensor Hub",
    "type": "sensor_hub",
    "manufacturer": "Custom",
    "model": "ESP32-WROOM-32",
    "protocol": "mqtt",
    "metadata": {
      "firmware_version": "1.0.0",
      "location": "Grow Tent 1"
    }
  }'

PUT/api/v1/devices/:id

Aktualisiert ein bestehendes Gerät.

curl -X PUT https://api.syngrow.com/v1/devices/device_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Sensor Hub",
    "status": "active"
  }'

DELETE/api/v1/devices/:id

Löscht ein Gerät und alle zugehörigen Daten.

curl -X DELETE https://api.syngrow.com/v1/devices/device_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Code-Beispiele

Beispielimplementierungen in verschiedenen Programmiersprachen

Python Beispiel

Vollständiges Beispiel zum Senden von Sensordaten mit Python:

import requests
import time
from datetime import datetime

class SynGrowClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.syngrow.com/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def send_reading(self, device_id, sensor_type, value, unit):
        """Send a single sensor reading"""
        data = {
            "device_id": device_id,
            "sensor_type": sensor_type,
            "value": value,
            "unit": unit,
            "timestamp": datetime.utcnow().isoformat() + "Z"
        }
        
        response = requests.post(
            f"{self.base_url}/readings",
            json=data,
            headers=self.headers
        )
        
        if response.status_code == 201:
            return response.json()
        else:
            raise Exception(f"Error: {response.status_code} - {response.text}")
    
    def send_batch_readings(self, device_id, readings):
        """Send multiple readings at once"""
        data = {
            "device_id": device_id,
            "readings": readings
        }
        
        response = requests.post(
            f"{self.base_url}/readings/batch",
            json=data,
            headers=self.headers
        )
        
        return response.json()

# Example usage
client = SynGrowClient("YOUR_API_KEY")

# Send single reading
try:
    result = client.send_reading(
        device_id="device_123",
        sensor_type="temperature",
        value=24.5,
        unit="celsius"
    )
    print(f"Reading sent: {result}")
except Exception as e:
    print(f"Error: {e}")

# Send batch readings
readings = [
    {
        "sensor_type": "temperature",
        "value": 24.5,
        "unit": "celsius",
        "timestamp": datetime.utcnow().isoformat() + "Z"
    },
    {
        "sensor_type": "humidity",
        "value": 65.2,
        "unit": "percent",
        "timestamp": datetime.utcnow().isoformat() + "Z"
    }
]

batch_result = client.send_batch_readings("device_123", readings)
print(f"Batch sent: {batch_result}")

Rate Limiting

Informationen zu API-Limits und Best Practices

API-Limits

• Anfragen pro Minute: 60 (Standard), 300 (Pro), 1000 (Enterprise)

• Batch-Größe: Max. 100 Messwerte pro Batch-Anfrage

• Payload-Größe: Max. 1 MB pro Anfrage

• Historische Daten: Max. 10.000 Datenpunkte pro Anfrage

Rate Limit Headers

Jede API-Antwort enthält Header mit Informationen zu Ihren verbleibenden Limits:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706353800

Best Practices

• Verwenden Sie Batch-Endpunkte für mehrere Messwerte
• Implementieren Sie exponentielles Backoff bei 429-Fehlern
• Cachen Sie häufig abgerufene Daten lokal
• Nutzen Sie Webhooks statt Polling für Echtzeit-Updates
• Komprimieren Sie große Payloads mit gzip

Webhooks

Empfangen Sie Echtzeit-Benachrichtigungen über Ereignisse

Webhooks ermöglichen es Ihrer Anwendung, Echtzeit-Benachrichtigungen über wichtige Ereignisse zu erhalten, ohne die API ständig abfragen zu müssen.

Verfügbare Webhook-Events

Sensor-Events

• sensor.alert.triggered
• sensor.reading.anomaly
• device.offline
• device.online

Grow-Events

• grow.phase.changed
• grow.completed
• grow.alert.critical
• grow.milestone.reached

Webhook-Konfiguration

Registrieren Sie einen Webhook-Endpunkt:

curl -X POST https://api.syngrow.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/syngrow",
    "events": [
      "sensor.alert.triggered",
      "device.offline",
      "grow.phase.changed"
    ],
    "secret": "your-webhook-secret"
  }'

Webhook-Payload Beispiel

Beispiel für einen sensor.alert.triggered Event:

{
  "id": "evt_1234567890",
  "type": "sensor.alert.triggered",
  "created": "2024-01-27T10:30:00Z",
  "data": {
    "device_id": "device_123",
    "sensor_type": "temperature",
    "current_value": 32.5,
    "threshold_type": "max",
    "threshold_value": 28.0,
    "grow_id": "grow_456",
    "alert_id": "alert_789"
  }
}

Webhook-Sicherheit

Verifizieren Sie Webhook-Signaturen mit HMAC-SHA256:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

# In your webhook handler
signature = request.headers.get('X-SynGrow-Signature')
if not verify_webhook(request.body, signature, webhook_secret):
    return 401  # Unauthorized

Fehlerbehandlung

HTTP Status Codes

• 200 OK - Anfrage erfolgreich

• 201 Created - Ressource erstellt

• 400 Bad Request - Ungültige Anfrage

• 401 Unauthorized - Fehlende/ungültige Authentifizierung

• 404 Not Found - Ressource nicht gefunden

• 429 Too Many Requests - Rate Limit überschritten

• 500 Internal Server Error - Serverfehler

Fehlerantwort-Format

{
  "error": {
    "code": "INVALID_SENSOR_TYPE",
    "message": "The sensor type 'temp' is not valid. Use 'temperature' instead.",
    "details": {
      "valid_types": ["temperature", "humidity", "ph", "ec", "co2", "light", "water_temp", "water_level"],
      "provided": "temp"
    }
  }
}

Support & Ressourcen

Entwickler-Ressourcen

Hilfe & Support

curl -X POST https://api.syngrow.com/v1/devices \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "ESP32 Sensor Hub", "type": "sensor_hub", "manufacturer": "Custom", "model": "ESP32-WROOM-32", "protocol": "mqtt", "metadata": { "firmware_version": "1.0.0", "location": "Grow Tent 1" } }'

curl -X PUT https://api.syngrow.com/v1/devices/device_123 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Sensor Hub", "status": "active" }'

import requests import time from datetime import datetime class SynGrowClient: def __init__(self, api_key): self.api_key = api_key self.base_url = "https://api.syngrow.com/v1" self.headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } def send_reading(self, device_id, sensor_type, value, unit): """Send a single sensor reading""" data = { "device_id": device_id, "sensor_type": sensor_type, "value": value, "unit": unit, "timestamp": datetime.utcnow().isoformat() + "Z" } response = requests.post( f"{self.base_url}/readings", json=data, headers=self.headers ) if response.status_code == 201: return response.json() else: raise Exception(f"Error: {response.status_code} - {response.text}") def send_batch_readings(self, device_id, readings): """Send multiple readings at once""" data = { "device_id": device_id, "readings": readings } response = requests.post( f"{self.base_url}/readings/batch", json=data, headers=self.headers ) return response.json() # Example usage client = SynGrowClient("YOUR_API_KEY") # Send single reading try: result = client.send_reading( device_id="device_123", sensor_type="temperature", value=24.5, unit="celsius" ) print(f"Reading sent: {result}") except Exception as e: print(f"Error: {e}") # Send batch readings readings = [ { "sensor_type": "temperature", "value": 24.5, "unit": "celsius", "timestamp": datetime.utcnow().isoformat() + "Z" }, { "sensor_type": "humidity", "value": 65.2, "unit": "percent", "timestamp": datetime.utcnow().isoformat() + "Z" } ] batch_result = client.send_batch_readings("device_123", readings) print(f"Batch sent: {batch_result}")

curl -X POST https://api.syngrow.com/v1/webhooks \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/syngrow", "events": [ "sensor.alert.triggered", "device.offline", "grow.phase.changed" ], "secret": "your-webhook-secret" }'

{ "id": "evt_1234567890", "type": "sensor.alert.triggered", "created": "2024-01-27T10:30:00Z", "data": { "device_id": "device_123", "sensor_type": "temperature", "current_value": 32.5, "threshold_type": "max", "threshold_value": 28.0, "grow_id": "grow_456", "alert_id": "alert_789" } }

import hmac import hashlib def verify_webhook(payload, signature, secret): expected = hmac.new( secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) # In your webhook handler signature = request.headers.get('X-SynGrow-Signature') if not verify_webhook(request.body, signature, webhook_secret): return 401 # Unauthorized

{ "error": { "code": "INVALID_SENSOR_TYPE", "message": "The sensor type 'temp' is not valid. Use 'temperature' instead.", "details": { "valid_types": ["temperature", "humidity", "ph", "ec", "co2", "light", "water_temp", "water_level"], "provided": "temp" } } }