Variomedia Kunden-API

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

Bemerkungen zum Alpha-Status

Authentifizierung

Authentifizierung findet mittels des Authorization:-Headers statt. Entweder als traditionelle HTTP Basic Authentication, hierbei nutzen Sie token als User und das Token selbst als Passwort. Alternativ kann auch die Methode token benutzt werden:

Authorization: token ihr-token

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.

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.

Job Queue

Die meisten Aktionen erfolgen asynchron. Deshalb erhalten Sie in der Regel eine HTTP-Response vom Code 202 Accepted und einen Link zu einem Job mit dem Status pending in der Queue.

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:

GET /queue-jobs/{id}

Liefert einen einzelnen Job anhand seiner ID zurück.

Hosting

Domains

GET /domains

Liefert eine Liste aller Domains mit Erstellungs- und Ablaufdatum.

GET /domains/{domain-name}

Liefert Details zur Domain {domain-name}.

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}.

GET /dns-records/{id}

Liefert Details zum DNS-Eintrag {id}.

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}.

POST /subdomains

Erstellt eine neue Subdomain anhand des POST-Bodys.

Derzeit können nur Subdomains vom Typ webspace angelegt werden.

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": "webspace",
    "attributes": {
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub",
      "webspace_path": "/sub-webspace/"
    }
  }
}

E-Mail-Adressen

GET /email-addresses

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

GET /email-addresses/{id}

Liefert Details zur E-Mail-Adresse mit der ID {id}.

Es gibt zwei Sorten von E-Mail-Adressen:

  1. mailbox: Die E-Mails lagern in einem Postfact 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 oder Weiterleitungsziele.

POST /email-addresses

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

Postfächer

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

{
  "data": {
    "type": "mailbox",
    "attributes": {
      "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": "forward",
    "attributes": {
      "description": "Eine freiwillige Beschreibung.",
      "address": "weiterleitung@beispielkunde.info",
      "forward_to": [
        "postfach1@beispielkunde.info",
        "postfach2@beispielkunde.info"
      ]
    }
  }
}