API-Dokumentation

API-Endpunkt

Du findest den HTTP-Endpunkt unter https://api.simply.com/2/ - Präfixiere deine Anfragen damit.

Beispiel: https://api.simply.com/2/my/products/

Authentifizierung

Die Authentifizierung erfolgt mit HTTP Basic Authentication.

Passwort ist der API-Schlüssel für das spezifische Konto.

Benutzername Kann alles sein, da der API-Schlüssel allein das Konto identifiziert.

Alternativ kann der API-Schlüssel als Bearer-Token im Authorization-Header gesendet werden:

Authorization: Bearer APIKEY

API-Schlüssel werden im Simply.com Kontrollpanel unter Konto, API-Schlüssel erstellt.

OpenApi-Spezifikation / Dokumentation

Du kannst die interaktive API-Dokumentation hier finden: https://api.simply.com/2/doc/

Oder OpenAPI-Spezifikation als JSON herunterladen: https://api.simply.com/2/doc.json

Ratenbegrenzungen

Die API unterliegt Ratenbegrenzungen, nur um Missbrauch zu verhindern.

Bei Überschreitung antwortet die API mit 429 und gibt die Wartezeit in Retry-After an.

Bibliotheksimplementierungen

Die folgenden Bibliotheken stehen zur Nutzung zur Verfügung.

ACME-Implementierungen

acme.sh	https://github.com/acmesh-official/acme.sh/
Posh-ACME	https://github.com/rmbolger/Posh-ACME/
cert-manager service	https://github.com/RunnerM/simply-dns-webhook/
Certbot plugin	https://github.com/JohNan/certbot-dns-simply/
Webhook provider for ExternalDNS	https://github.com/uozalp/external-dns-simply-webhook

API-Implementierungen

PHP	https://github.com/simplycom/api-php/

ddns.simply.com (DynDNS2)

Router und DDNS-Clients, die das DynDNS2-Protokoll unterstützen, können den Host ddns.simply.com direkt nutzen.

Für Skripte und andere Automatisierung von DNS empfehlen wir die REST-API, die DNS-Einträge erstellen, ändern und löschen kann.

https://ddns.simply.com/nic/update?hostname=home.example.com&domain=example.com&myip=1.2.3.4

Authentifizierung erfolgt mit HTTP Basic Authentication, wobei das Passwort der API-Schlüssel des Kontos ist. Der Benutzername kann beliebig sein, z. B. der Kontoname.

Wird myip weggelassen, wird die IP-Adresse verwendet, von der die Anfrage stammt. Updates müssen über HTTPS erfolgen.

Der Eintrag muss in der DNS-Zone gefunden werden, bevor er aktualisiert werden kann: ein A-Record für IPv4 und ein AAAA-Record für IPv6. Wird er nicht gefunden, wird nohost zurückgegeben, also erstelle den Eintrag zuerst im Kontrollpanel.

Der Parameter domain gibt die Domain an. Er muss mitgesendet werden, wenn die Domain selbst aktualisiert wird, z. B. hostname=example.com&domain=example.com, und kann verwendet werden, wenn die Domain nicht aus hostname abgeleitet werden kann.

Die Antworten folgen dem DynDNS2-Protokoll, z.B. good bei einer Aktualisierung und nochg, wenn die IP-Adresse unverändert ist.

Die Adresse https://ddns.simply.com/myip gibt die öffentliche IP-Adresse zurück, von der die Anfrage stammt, und erfordert keine Authentifizierung.

ddclient

protocol=dyndns2
ssl=yes
server=ddns.simply.com
login=ACCOUNTNAME
password=APIKEY
home.example.com

Curl-Beispiel (Empfohlen)

Verwende den folgenden Curl-Befehl, um zu setzen home.example.com zur externen IP des anfragenden Clients:

curl -s -u "ACCOUNTNAME:APIKEY" "https://ddns.simply.com/nic/update?hostname=home.example.com"

Du kannst diesen Befehl so einstellen, dass er in einer Crontab, auf einem lokalen Rechner, alle 15 Minuten oder etwa so läuft.

Synology

Bei Synology kannst du die folgende Syntax als Custom DDNS Provider verwenden.

https://ddns.simply.com/nic/update?hostname=__HOSTNAME__&myip=__MYIP__

hostname Muss anschließend als der vollqualifizierte Domainname angegeben werden, den du aktualisieren möchtest, z. B. home.example.com.

Home Assistant

Der Sensor holt die öffentliche IP-Adresse alle 5 Minuten, und die Automation aktualisiert DNS nur, wenn sich die Adresse ändert und wenn Home Assistant startet. Der API-Schlüssel wird in secrets.yaml gespeichert.

# configuration.yaml
sensor:
  - platform: rest
    name: Public IP
    resource: https://ddns.simply.com/myip
    value_template: "{{ value | trim }}"
    scan_interval: 300

rest_command:
  simplycom_ddns:
    url: "https://ddns.simply.com/nic/update?hostname=home.example.com"
    username: "ACCOUNTNAME"
    password: !secret simply_api_key

# secrets.yaml
simply_api_key: "APIKEY"

# Automation
alias: Simply.com DDNS
triggers:
  - trigger: state
    entity_id: sensor.public_ip
  - trigger: homeassistant
    event: start
actions:
  - action: rest_command.simplycom_ddns

Unifi

In UniFi OS musst du einen Custom Dynamic DNS-Provider einrichten und die folgende Zeichenkette in das Feld "Server" eingeben.

ddns.simply.com/nic/update?hostname=%h&myip=%i

Simply.com API-Dokumentation