Variomedia Kunden-API

Unsere Kunden-API ermöglicht es allen Kunden wiederkehrende Vorgänge wie die Verwaltung von DNS-Einträgen oder das Anlegen von E-Mail-Adressen zu automatisieren.

Die API orientiert sich an der JSON:API-Spezifikation. Authentifizierung erfolgt über API Tokens, die für einzelne Kundenkontakte freigeschaltet werden müssen.

Unsere FAQ enthält praktische Beispiele (zum Beispiel Let’s Encrypt/certbot-Integration) und weitere Informationen.

Derzeit muss der Zugang noch manuell freigeschaltet werden. Eine Integration mit dem Kundenmenü ist in Arbeit, jedoch noch nicht abgeschlossen. Bis es soweit ist, wenden Sie sich bitte an die Kundenbetreuung – wir stellen Ihnen sehr gern einen Token aus.

Informationen zu unserer alten Reseller-API finden Sie unter /docs/legacy. Die alten API-Endpunkte funktionieren wie gewohnt und werden solange betrieben, bis die neue API volle Funktionsparität bietet.

Änderungen

2020-07-02

Es ist nun möglich, Web-Redirect-Subdomains anzulegen.

2020-06-16

Es ist nun möglich, Email-Subdomains anzulegen.

2020-06-11

Application Passwords für Email-Postfächer können nun angelegt und gelöscht werden.

2020-06-10

  • Die Standard-PHP-Version für Webhosting-Subdomains kann nun gesetzt werden.
  • Der Webspace-Pfad von Webhosting-Subdomains kann nun gesetzt werden.

2020-05-19

Der DNS-Migrationsmodus kann nun für Domains gesetzt werden.

2020-03-06

Es ist nun möglich, Autorespondern von E-Mail-Postfächern ein Ablaufdatum zuzuordnen.

2019-10-25

Es ist nun möglich E-Mail-Adressen serverseitig nach Adressen zu filtern.

2019-08-14

Beschreibungen (description) von E-Mailadressen können nun mittels PATCH geändert werden.

2019-08-13

Beim Anlegen von E-Mailadressen ist es nun möglich den Spamschutz zu konfigurieren. Wir raten jedoch dazu, den Standardwert reject nicht zu ändern.

2019-08-12

  • Autoresponder können nun gesetzt, aktiviert und deaktiviert werden.
  • Statt neue Postfachpasswörter von Hand zu setzen, ist es nun auch möglich mittels eines POSTs ein neues, sicheres Passwort zu setzen

2019-08-09

E-Mail-Adressen mit +-Zeichen können nun als Weiterleitungsziele (forward_to) für Postfächer und Weiterleitungen verwendet werden.

2019-08-08

Postfachpasswörter können nun geändert werden.

2019-06-11

Es ist nun möglich, bei E-Mail-Adressen zusätzliche Empfänger hinzuzufügen und zu löschen.

2019-05-17

E-Mail-Adressen können nun gelöscht werden.

2019-03-06 → Ende der Betaperiode

Die meisten Änderungen ergeben sich aus der Tatsache, dass einige Entscheidungen dem JSON:API-Standard widersprachen. Insbesondere müssen Untertypen die bisher per /data/type gesetzt wurden, nun unterhalb der attributes gesetzt werden und der Name darf nicht type sein.

  • /dns-records:
    • Beim Abruf heisst /data/attributes/type nun /data/attributes/record_type.
    • Beim Anlegen muss das type-Feld nun immer dns-record lauten. Der Untertyp wird mittels /data/attributes/record_type definiert.
  • /domain-availability: Die Ergebnisse sind nun ebenfalls nach JSON:API-Art gewrapt.
  • /email-addresses:
    • Beim Abruf heisst /data/attributes/type nun /data/attributes/address_type.
    • Beim Anlegen muss das type-Feld nun immer email-address lauten. Der Untertyp wird mittels /data/attributes/address_type definiert.
  • /queue-jobs: /data/attributes/type heisst nun /data/attributes/job_type.
  • /subdomains:
    • Beim Abruf heisst /data/attributes/type nun /data/attributes/subdomain_type.
    • Beim Anlegen muss das type-Feld nun immer subdomain lauten. Der Untertyp wird mittels /data/attributes/subdomain_type definiert.

2019-02-26

  • /domain-availability: Domains können nun auf Verfügbarkeit geprüft werden.
  • /subdomains: Beim Anlegen von Webhosting-Subdomains kann nun optional die PHP-Version angegeben werden.

Allgemeine Prinzipien

Authentifizierung

Authentifizierung findet mittels des Authorization:-Headers statt.

Um das Testen in Browsern zu ermöglichen, ist es möglich traditionelle HTTP Basic Authentication zu verwenden. Hierbei nutzen Sie token als User und den Token selbst als Passwort.

Alternativ kann auch die Methode token benutzt werden:

Authorization: token ihr-token

Tokens deren Kontakte gelöscht werden, werden automatisch ungültig.

Content-Type

Vorzugsweise sollten Sie Ihre Request mit dem Content-Type application/vnd.api+json verschicken. Die API verlangt das jedoch nicht und sollte es nicht gesetzt sein, sind die Server-Antworten als application/json angegeben, um das Testen im Browser zu erleichtern.

Bei allen Requests, die eine JSON-Payload im Body haben, muss der Content-Type auf entweder application/vnd.api+json oder application/json gesetzt werden.

Versionierung

Versionierung findet per Accept:-Header statt. Die aktuelle Version lautet:

Accept: application/vnd.variomedia.v1+json

Wird keine Version angegeben, erhalten Sie automatisch die neuste Version.

Wir empfehlen daher immer explizit eine API-Version zu setzen.

Rückwärtskompatible Änderungen wie das Hinzufügen von Attributen in Responses veranlassen keine Änderung der API-Version.

Limits

Derzeit besteht eine Durchsatzbegrenzung (Rate-Limit) von 10 Request / 10 Sekunden per IP. Sollte sie überschritten werden, liefert die API Statuscode 429 zurück.

Sollten Sie zu viele Fehler verursachen, wird der Zugang zur API vorrübergehend gesperrt.

Job Queue

Bei Schreiboperationen, kann es vorkommen, dass bestimmte Aktionen asynchron erfolgen und mehrere Minuten brauchen, bis sie erledigt sind.

In dem Fall erhalten Sie vom Server ein 202 Accepted zurück zusammen mit einer Link zu einem Job der den Status pending hat.

Sobald ein Job erfolgreich abgearbeitet ist, wird sein Status auf done gesetzt.

GET /queue-jobs

Gibt Ihnen eine Liste von Jobs die im Status pending sind.

Anhand von /data/links/object lässt es sich auf das Objekt schließen, das erstellt/bearbeitet wird und anhand von /data/relationsships/owner/data/id können Reseller die Jobs ihren Endkunden zuordnen.

Bitte beachten:

  • Erledigte Jobs werden nach 24h gelöscht.
  • Im Kundenmenü ausgelöste Jobs erscheinen hier nicht.
GET /queue-jobs/{id}

Liefert einen einzelnen Job anhand seiner ID zurück.

Domains

Domains können:

  1. über Variomedia registriert,
  2. einer Präsenz zugeordnet (d.h. sie wird bei Variomedia genutzt, aber woanders registriert; auch „externe Domain“ genannt),
  3. beides sein.

Deshalb enthält die Reponse zwei Unterfelder: registration und presence. Je nach Domaintyp, kann eines der beiden Felder null sein, was eine Unterscheidung ermöglicht.


GET /domains

Liefert eine Liste aller Domains mit Erstellungs- und Ablaufdatum.

GET /domains/{domain-name}

Liefert Details zur Domain {domain-name}.

Manipulation von Domains

PATCH /domains/{domain-name}

Ermöglicht die Manipulation von existierenden Domains. Bitte beachten Sie, dass die Domain in der URL und das id-Feld im Body identisch sein müssen.

DNS-Updateschutz

Den Updateschutz für DNS-Einträge aktiveren, beziehungsweise deaktivieren:

{
    "data": {
        "id": "beispielkunde.info",
        "type": "domain",
        "attributes": {
            "presence": {
                "dns_update_lock": false
            }
        }
    }
}

DNS-Migrationsmodus

Analog können Sie ebenfalls den DNS-Migrationsmodus beeinflussen:

{
    "data": {
        "id": "beispielkunde.info",
        "type": "domain",
        "attributes": {
            "presence": {
                "dns_migration_mode": {
                    "enabled": true
                }
            }
        }
    }
}

Verfügbarkeit von Domains

Mittels

GET /domain-availability/domain1.de,domain2.de,...

können Sie überprüfen, ob eine Domain zur Registrierung zur Verfügung steht.

Falls available den Wert null hat, bedeutet es, dass ein Fehler aufgetreten ist.

Bitte beachten Sie, dass die Geschwindigkeit und Zuverlässigkeit dieses Endpunktes von den eigentlichen Domain-Registries abhängt. Unterschiedliche TLDs dauern unterschiedlich lange und manche Registries neigen zu Ausfällen.

Limits

Derzeit können maximal 10 Domains gleichzeitig überprüft werden.

DNS-Einträge

GET /dns-records

Liefert eine Liste aller DNS-Einträge.

GET /dns-records?filter[domain]={domain}

Liefert eine Liste aller DNS-Einträge für die Domain {domain}. Sie können sowohl den filter[domain]-Parameter mehrfach anwenden, als auch mehrere Domains durch Kommas trennen.

GET /dns-records/{id}

Liefert Details zum DNS-Eintrag {id}.

POST /dns-records

Erstellt einen neuen DNS-Eintrag anhand des POST-Bodys.

Derzeit können folgende Typen von DNS-Einträgen erstellt werden:

Zum Beispiel:

{
  "data": {
    "type": "dns-record",
    "attributes": {
      "record_type": "A",
      "name": "local",
      "domain": "domain.de",
      "data": "127.0.0.1",
      "ttl": 800
    }
  }
}

legt einen A-Eintrag für die Domain local.domain.de mit der Adresse 127.0.0.1 an.

  • Das Feld domain muss eine Präsenz-Domain sein.
  • Das ttl (Time To Live) Feld ist in Sekunden (300–86400) und optional. Beim Fehlen wird der gleiche Systemdefault benutzt, wie im Kundenmenü.

Besonderheiten:

  • CNAME-Einträge werden im Gegensatz zum Kundenmenü immer absolut interpretiert. Die data-Felder foo.com und foo.com. werden also identisch behandelt.
DELETE /dns-records/{id}

Löscht einen DNS-Eintrag mit der id {id}.

Bitte beachten Sie:

  • Gelöschte DNS-Einträge können nicht ohne weiteres wiederhergestellt werden!

  • Falls Sie die DNS-Einträge, die das base-Tag im Kundenmenü tragen ändern möchten, sollten Sie unbedingt den Update-Schutz aktivieren, damit Vorgänge wie Tarifwechsel sie nicht zurücksetzen.

    Sie können dies entweder von Hand im Kundenmenü oder mit Hilfe des Domain-Endpunktes dieser API erledigen.

Subdomains

Es gibt drei Typen von Subdomains:

  1. webspace: Volles Webhosting und E-Mail.
  2. redirect: HTTP-Redirect und E-Mail.
  3. email: Subdomain die ausschließlich für E-Mail genutzt wird.
GET /subdomains

Liefert eine Liste von Subdomains für den aktuellen Kunden.

GET /subdomains/{id}

Liefert Details zur Subdomain mit der ID {id}.

Erstellen

POST /subdomains

Erstellt eine neue Subdomain anhand des POST-Bodys.

Webspace

Ein Beispiel für einen POST-Body, der eine Webspace-Subdomain „sub“ für die Domain „domain.de“ anlegt, die auf den Pfad „/sub-webspace/“ zeigt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "webspace",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub",
      "webspace": {
        "path": "/sub-webspace/"
      }
    }
  }
}

Optional kann zusätzlich eine php_version als String übergeben werden, die standardmäßig für PHP-Skripte verwendet wird. Beim Weggelassen wird automatisch die empfohlene PHP-Version verwendet.

Derzeit sind folgende Versionen zulässig:

  • "5.6" (keine Sicherheitsupdates mehr verfügbar!)
  • "7.1" (keine Sicherheitsupdates mehr verfügbar!)
  • "7.2" (unterstützt bis 30.11.2020)
  • "7.3" (unterstützt bis 06.12.2021)
  • "7.4" (unterstützt bis 28.11.2022)

Redirect

Ein Beispiel für einen POST-Body, der eine Redirect-Subdomain „sub“ für die Domain „domain.de“ anlegt, die Zugriffe nach „sub2.domain.de“ mittels eines Location-Headers weiterleitet und den Pfad dynamisch umschreibt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "redirect",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub",
      "redirect": {
        "dynamic": true,
        "target": "https://sub2.domain.de/"
      }
    }
  }
}

Ist dynamic auf false gesetzt, wird hart auf die target-URL umgeleitet. Wenn es true ist, wird der Pfad übernommen. Also z.B. https://sub.domain.de/foo/bar würde auf https://sub2.domain.de/foo/bar umleiten.

Für die target-URL gelten die gleichen Regeln, wie im Kundenmenü.

Email

Ein Beispiel für einen POST-Body, der eine Email-Subdomain „sub“ für die Domain „domain.de“ anlegt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "email",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub"
    }
  }
}

Manipulation

PATCH /subdomains/{id}

Erlaubt die Manipulation existierender Subdomains. Bitte beachten Sie, dass die ID in der URL und das id-Feld im Body identisch sein müssen.

PHP-Version

Für Webspace-Subdomains können Sie die Standard-PHP-Version setzen:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "webspace": {
        "php_version": "7.4"
      }
    }
  }
}

Für gültige Versionen, vergleichen Sie bitte die Liste von oben. Bei null wird die Standardversion des Pakets, in dem sich die Subdomain befindet, verwendet.

Pfad zu Webspace

Um den Webspace-Pfad zu setzen:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "webspace":{
        "path": "/ihr/wordpress/"
      }
    }
  }
}

Redirect-Ziel

Um die Ziel-URL einer Redirect-Subdomain zu ändern:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "redirect": {
        "target": "https://beispielkunde.info/"
      }
    }
  }
}

Sollte die Subdomain bisher uninitialisiert sein (d.h in der Liste erscheint sie als Weiterleitung, jedoch ohne Weiterleitungsdaten), wird im gleichen Schritt die Weiterleitung as statisch eingerichtet.

Dynamische Redirects

Sie können eine Redirect-Subdomain dynamisch machen (oder nicht). Bitte beachten Sie, dass um eine Redirect-Subdomain dynamisch zu machen, die Ziel-URL mit einem / enden muss.

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "redirect": {
        "dynamic": true
      }
    }
  }
}

Es ist nicht möglich dies für uninitialisierte Subdomains anzuwenden.

E-Mail-Adressen

GET /email-addresses

Liefert eine Liste aller E-Mail-Adressen für den aktuellen Kunden.

Es ist möglich diese Liste nach konkreten Adressen zu filtern:

GET /email-addresses?filter[address]=info@beispielkunde.de

Sie können sowohl den filter[address]-Parameter mehrfach anwenden, als auch mehrere Adressen durch Kommas trennen.

Falls Sie die ID einer Adresse haben, können sie sie auch direkt abrufen:

GET /email-addresses/{id}

Es gibt zwei Sorten von E-Mail-Adressen:

  1. mailbox: Die E-Mails lagern in einem Postfach auf unseren Servern und werden mittels IMAP oder Webmail abgerufen. Optional ist zusätzlich eine Weiterleitung möglich.
  2. forward: Die E-Mails werden ausschließlich weitergeleitet.

Je nach Typ enthalten die Details Zusatzinformationen, wie zum Beispiel Postfach-Quotas.

Anlegen von Adressen

POST /email-addresses

Erstellt eine neue E-Mail-Adresse anhand des POST-Bodys.

Mögliche Felder:

  • address: Die Adresse die Sie anlegen möchten. Sie darf nicht existieren und die Domain muss Teil Ihres Kundenkontos sein.
  • address_type: Muss mailbox oder forward sein.
  • description: Optional, Default: null. Beschreibung der Adresse die im Kundenmenü und in der API angezeigt wird.
  • antispam: Optional, Default: reject. Die Spamschutzeinstellungen für die neue E-Mail-Adresse. Muss eines von reject, junk-folder (nur Mailboxen), subject-rewrite oder none sein. Wir empfehlen dringend, diese Einstellung nicht zu ändern.
  • forward_to: Optional für Mailboxen, jedoch Pflicht für Weiterleitungen. Eine Liste von E-Mail-Adressen, an die jede E-Mail weitergeleitet wird.

Postfächer

Ein Beispiel für einen POST-Body, der ein Postfach mit der E-Mail-Adresse „postfach@beispielkunde.info“ anlegt:

{
  "data": {
    "type": "email-address",
    "attributes": {
      "address_type": "mailbox",
      "description": "Eine freiwillige Beschreibung.",
      "address": "postfach@beispielkunde.info",
      "forward_to": []
    }
  }
}

Ein sicheres Passwort für das Postfach wird automatisch generiert und mit der Bestätigung zurückgegeben.

Weiterleitungen

Ein Beispiel für einen POST-Body, der eine E-Mail-Adresse „weiterleitung@beispielkunde.info“ anlegt, dessen E-Mails an „postfach1@beispielkunde.info” und „postfach2@beispielkunde.info” weitergeleitet werden:

{
  "data": {
    "type": "email-address",
    "attributes": {
      "address_type": "forward",
      "description": "Eine freiwillige Beschreibung.",
      "address": "weiterleitung@beispielkunde.info",
      "forward_to": [
        "postfach1@beispielkunde.info",
        "postfach2@beispielkunde.info"
      ]
    }
  }
}

Manipulation von Adressen

PATCH /email-addresses/{id}

Erlaubt die Manipulation von existierenden Adressen. Bitte beachten Sie, dass die ID in der URL und das id-Feld im Body identisch sein müssen.

Postfachpasswörter

Folgender Body für PATCH /email-addresses/42 ändert das Passwort auf "lieber laenger, als kuerzer":

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "password": "lieber laenger, als kuerzer"
    }
  }
}

Bitte beachten Sie, dass zu Ihrer Sicherheit strikte Anforderungen an die Passwörter gestellt werden:

  • Mindestens 16 Zeichen lang.
  • Mindestens 10 davon müssen sich unterscheiden (groß/klein reicht nicht).
  • Gültige Zeichen sind:
    • alle Buchstaben ohne Umlaute (A–Z und a–z)
    • alle Zahlen (0–9)
    • das Leerzeichen
    • die folgenden Sonderzeichen: ., ,, $, /, _, *, !, #, @, +, -, und &.
  • Weder der Nutzername noch die Domain dürfen in irgendeiner Form im Passwort vorkommen.
  • Die Wörter "Variomedia", "vrmd", "Securehost", "Password" und "Passwort" dürfen nicht im Passwort vorkommen.
  • Das Beispielpasswort von oben ist nicht zulässig.
  • Zeichenfolgen wie qwert oder asdf dürfen nicht im Passwort vorkommen.
  • Zusätzlich wird überprüft, dass das Passwort nicht in einer der gängigen Listen von geleakten Passwörtern auftaucht.

Sollten Sie einfach nur ein neues, sicheres Passwort wünschen, benutzen Sie den folgenden Endpunkt:

POST /email-addresses/{id}/password

Das Postfach erhält ein neues, zufällig generiertes Passwort und es wird im Response-Body zurückgeliefert.

Application Passwords

Sie können mittels

POST /email-addresses/{id}/application-passwords

Sich ein neues Application Password zurückgeben lassen. Im Body müssen Sie die Attribute device und application setzen. Diese sind frei wählbar, dürfen jedoch nicht leer sein:

{
  "data": {
    "type": "application-password",
    "attributes": {
      "device": "Mobiltelefon",
      "application": "Mail"
    }
  }
}

Application Passwords können mit ihrer ID gelöscht werden:

DELETE /email-addresses/{address-id}/application-passwords/{application-password-id}

Zusätzliche Weiterleitungen

Sowohl Postfächer, als auch Weiterleitungen erlauben es, zusätzliche Empfänger zu definieren (/data/attributes/forward_to).

Als Komfortfunktion können Sie diese Weiterleitungen einzeln von Hand hinzufügen:

POST /email-addresses/{id}/forward-to/weiterleitungsziel@beispielkunde.info

und entfernen:

DELETE /email-addresses/{id}/forward-to/weiterleitungsziel@beispielkunde.info

Autoresponder

Ändern des Textes

Um den Autoresponder-Text für die Adresse mit der ID 42 zu ändern senden sie den folgenden Body an PATCH /email-addresses/42:

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "autoresponder": {"text": "Ich bin im Urlaub."}
    }
  }
}

Aktivieren und deaktivieren

Das Aktivieren und Deaktivieren eines Autoresponders funktioniert analog zum Ändern des Textes:

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "autoresponder": {"active": true}
    }
  }
}

Automatische Deaktivierung

Auf die gleicher Art können Sie ein Datum hinzufügen, an dem Ihr Autoresponder automatisch kurz nach Mitternacht deutscher Zeit deaktiviert wird:

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "autoresponder": {"expires": "2020-03-06"}
    }
  }
}

Bitte verwenden Sie ausschließlich das ISO 8609-Format für das Datum, wie im Beispiel oben demonstriert.

Um eine automatische Deaktivierung zu entfernen, benutzen Sie null als Wert für expires.


Bitte beachten Sie, dass derzeit nur ein Attribut pro Request geändert werden kann. Entsprechend kann es sein, dass Sie insgesamt bis zu drei Requests brauchen, um Ihren Autoresponder zu konfigurieren.

Beschreibung

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "description": "Eine Beschreibung der E-Mailadresse."
    }
  }
}

Setzt die Beschreibung für eine E-Mailadresse. Wenn Sie die Beschreibung entfernen möchten, setzen Sie sie auf null.

Spamschutz

Sie können PATCH ebenfalls verwenden, um den Spamschutz zu ändern:

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "antispam": "reject"
    }
  }
}

Die gültigen Werte entnehmen Sie bitte von oben.

Löschen von Adressen

DELETE /email-addresses/{id}

Erlaubt es Ihnen ein Postfach oder eine Weiterleitung permanent zu löschen.