Allgemeine Prinzipien

Basis-URL

Sämtliche URLs sind relativ zum Hostnamen https://api.variomedia.de/.

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.

Einzige Ausnahme: Reseller können ihr altes API-Passwort weiterhin im Verfügbarkeit von Domains benutzen. Es handelt sich um HTTP Basic Authentication, wobei der Benutzername Ihre Kundennummer (ohne führende Nullen) ist.

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.

Passwörter

Sämtliche API-Endpunkte die irgendeine Art von Accounts erstellen, generieren automatisch sichere Passwörter. Manchmal ist es notwendig, ein Passwort manuell zu setzen oder zu ändern. Dafür besitzen einige Endpunkte Wege dies zu tun, haben jedoch hohe Anforderungen an Ihre Passwörter:

• 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)
  • alle Sonderzeichen aus der OWASP-Liste.
• Weder der jeweilige 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 Passwörter aus unseren Beispielen sind 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.