Logo Claim_de

Two-DNS API v2

Mit der Two-DNS API können Sie auf alle Dienste von Two-DNS zugreifen, es müssen jedoch folgende Anforderungen erfüllt sein:

Bestätigter Account

Nachdem Sie einen Account erstellt haben, müssen Sie diesen bestätigen, indem Sie auf den Link in der Bestätigungs-Email klicken.

API-Token

Die nicht-öffentlichen Angebote der API sind mit HTTP Basic Authentication gesichert. Um Zugang zu diesen Diensten zu bekommen, müssen Sie sich mit ihrer E-Mail und ihrem API-Token, den Sie nach der Erstellung eines Accounts erhalten, authentifizieren.

Authentifizierung Nach oben

Um Zugang zu einigen Two-DNS Angeboten per API zu erhalten, müssen Sie sich mit ihrer Email-Addresse und ihrem API-Token authentifizieren. Diesen finden Sie in ihrer Profil-Übersicht unter “API-Token”.

Das Authentifizierungsverfahren ist HTTP Basic Authentication. Normalerweise verlangt dieses Verfahren einen Benutzernamen und ein Passwort. Um auf nicht-öffentliche Dienste der Two-DNS API zuzugreifen, benutzen Sie ihre Email-Addresse als Benutzernamen und ihren API-Token als Passwort. Der API-Token dient als Sicherheitsmaßnahme: sobald dieses kontaminiert ist, d.h. wenn er sichtbar und zugänglich für eine dritte Person ist, können Sie im Dashboard einen neuen beantragen womit der alte ungültig wird und keinen Zugriff mehr auf ihre Daten per API bietet.

Es ist nicht nötig ihr Passwort an die API zu senden. Die einzige Ausnahme ist das Erstellen eines Benutzeraccounts über die API. Aber keine Sorge: die API ist mit SSL gesichert.

Beispiel:

Die Erstellung eines Hosts ist ein nicht-öffentlicher Dienst der API. Um einen Host zu erstellen, müssen Sie sich mit ihrer Email-Addresse und ihrem API-Token authentifizieren.

Erstellen wir also einen Host mit dem namen subdomain für die Domain twodns.de. Hierzu benötigen wir zudem einige andere Informationen: ttl, ip_address und ob eine Wildcar aktiviert werden soll (activate_wildcard).

Um mittels dem Kommandozeilenprogramm curl einen Host zu erstellen, muss ich folgende Parameter angeben um einen host zu erstellen:

curl -X POST –user “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ –data ’{“hostname”:“subdomain”, “ip_address”:“91.181.24.121”, “ttl”:“14400”,\ “activate_wildcard”:“true”, “domainname”:“twodns.de” }’ https://api.twodns.de/users

Erklärung:

-u/--user: sagt curl, HTTP Basic Auth zu benutzen. Wie bereits erwähnt: Wir benutzen die Email-Addresse als Benutzername und den API-Token als Passwort.

-d/--data: benötigt um die Eigenschaften des gewünschten Hosts an die API zu
schicken.

Domains Nach oben

Auflistung aller Domains

GET Anfrage an https://api.twodns.de/domains um eine Auflistung aller
verfügbaren Domains zu erhalten.

Beispiel:

curl -X GET https://api.twodns.de/domains

Antwort:

GET /domains HTTP/1.1 Host: https://api.twodns.de Content-Type: application/json; charset=utf-8 Status: 200 OK [ { “name”: “twodns-domain.de” }, { “name”: “twodns.de” } ]

Benutzeraccount Nach oben

Informationen über den eigenen Benutzeraccount

Authentifizierung benötigt:
GET Anfrage an https://api.twodns.de/users/me um Informationen über den eigenen Account zu erhalten.

Beispiel:

curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/users/me

Antwort:

GET /users/me HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 { “api_token”: “42fcb5dd5f6553f90676a98523e6e22d87944c33”, “email”: “joe@apiuser.de”, “max_allowed_hosts”: 5, “hosts”: [ { “activate_wildcard”: true, “fqdn”: “my.twodns-domain.de”, “ip_address”: “81.12.12.12”, “ttl”: 14400 }, { “activate_wildcard”: true, “fqdn”: “doodeeloo.twodns-domain.de”, “ip_address”: “81.12.12.12”, “ttl”: 14400 } ] }

Hosts Nach oben

Erstellen eines Hosts

Authentifizierung benötigt:
POST Anfrage an https://api.twodns.de/hosts mit hostname, ip_address, ttl, activate_wildcard und domainname als Daten.

Anfragedaten:

  • fqdn (String)

    Mögliche Werte:

    • [host].[domain]

    Sie erhalten eine Auflistung aller verfügbaren Domains indem Sie eine GET
    Anfrage an https://www.twodns.de/api/domains senden.

    Beispiel:
    Falls Sie einen Host mit dem Namen ‘myserver’ für die Domain 'twodns.de’
    erstellen möchten, ist der Wert von fqdn 'myserver.twodns.de'.

  • ip_address (String)

    Mögliche Werte:

    • '81.121.90.105' (Beispiel) – Die IP auf die ihr Host verweisen soll.
    • 'auto' – Falls Sie eine Anfrage an die API schicken um die IP-Addresse ihres Hosts auf 'auto' zu setzen, zeigt der Host automatisch auf die IP des Absenders.

  • ttl (Integer)

    Mögliche Werte:

    • 60
    • 300,
    • 14400,
    • 86400

  • activate_wildcard (Boolean)

Beispiel:

curl -v -X POST -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ -d ’{“fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “ttl”: “60”,\ “activate_wildcard”: “true”}’ https://api.twodns.de/hosts

Antwort:

POST /hosts HTTP/1.1 Host: https://api.twodns.de Status: 201 Created Content-Type: application/json; charset=utf-8 { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }
Fehler:

  • Bei der Benutzung von falschen Attributen antwortet der Server mit 422 Unprocessable Entity.

  • Falls der Host nicht erstellt werden konnte (weil z.B. der Hostname schon
    vergeben war), ist die Antwort 422 Unprocessable Entity und die
    Fehlermeldungen. Beispiel:

    • Anfrage:

      curl -v -X POST -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ -d ’{“fqdn”:“sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “ttl”: “60”,\ “activate_wildcard”: “true”}’ https://api.twodns.de/hosts

    • Antwort:

      POST /hosts HTTP/1.1 Host: https://api.twodns.de Status: 422 Content-Type: application/json; charset=utf-8 { “hostname”: [ “has already been taken” ] }

Informationen über alle eigenen Hosts

Authentifizierung benötigt:
GET Anfrage an https://api.twodns.de/hosts um Informationen über alle eigenen Hosts zu erhalten.

Beispiel:

curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hosts

Antwort:

GET /hosts HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }, { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “mywan.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/mywan.twodns-domain.de” } ]

Informationen über einen Host

Authentifizierung benötigt:
GET Anfrage an https://api.twodns.de/hosts/[host_fqdn] um Informationen über einen Host zu erhalten.

Beispiel:

curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hosts/sub.twodns-domain.de

Antwort:

GET /hosts/sub.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }

Einen Host updaten

Authentifizierung benötigt:
PUT Anfrage an https://api.twodns.de/hosts/[host_fqdn].

Anfragedaten:

  • ip_address (String)

    Mögliche Werte:

    • '81.121.90.105' (Beispiel) – Die IP auf die ihr Host verweisen soll.
    • 'auto' – Falls Sie eine Anfrage an die API schicken um die IP-Addresse ihres Hosts auf 'auto' zu setzen, zeigt der Host automatisch auf die IP des Absenders.

  • ttl (Integer)

    Mögliche Werte:

    • 60
    • 300,
    • 14400,
    • 86400

  • activate_wildcard (Boolean)

Sie können mit einer Anfrage entweder nur eine oder sogar alle Attribute updaten.

Falls Sie versuchen eine Eigenschaft eines Hosts zu updaten, die hier nicht aufgeführt ist, antwortet der Server mit 422 Unprocessable Entity.

Beispiele:

curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”}’ https://api.twodns.de/hosts/sub.twodns-domain.de
curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”, “activate_wildcard”: “true”}’ https://api.twodns.de/hosts/sub.twodns-domain.de

Antwort:

PUT /hosts/sub.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” } ]

Alle Hosts updaten:

Authentifizierung benötigt:
Fast das Gleiche, wie einen einzigen Host zu updaten, es muss lediglich [host_fqdn] am Ende der API-URL in all umgeändert werden:
PUT Anfrage an https://api.twodns.de/hosts/all.

Beispiel:

curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”, “activate_wildcard”: “true”}’ https://api.twodns.de/hosts/all

Antwort:

PUT /hosts/all HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }, { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “mywan.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/mywan.twodns-domain.de” } ]

Löschen eines Hosts

DELETE Anfrage an https://api.twodns.de/hosts/[host_fqdn]: der Server antwortet mit 204 No Content, falls der Host erfolgreich gelöscht wurde.

Beispiel:

curl -v -X DELETE -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hosts/my.twodns-domain.de

Antwort:

DELETE /hosts/my.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 204 No Content

Fehler & Antworten Nach oben

JSON Parse Error

Falls invalides JSON an den Server geschickt wird, antwortert dieser mit 400 Bad Request:

POST /users HTTP/1.1 Host: https://api.twodns.de Status: 400 Bad Request Content-Type: application/json; charset=utf-8 { “message”: “JSON could not be parsed” }

Resource not found

Falls mit einer ungültigen URL versucht wird auf eine nicht aufzufindende Ressource zuzugreifen, antwortet der Server mit 404 Not Found.

GET /hosts/non.existant.de HTTP/1.1 Host: https://api.twodns.de Status: 404 Not Found Content-Type: application/json; charset=utf-8 { “message”: “Sorry, resource does not exist” }

Wrong Attributes

Falls Attribute an den Server gesandt werden, um eine Ressource zu updaten, antwortet der Server mit 422 Unprocessable Entity:

POST /users HTTP/1.1 Host: https://api.twodns.de Status: 422 Unprocessable Entity Content-Type: application/json; charset=utf-8 { “message”: “JSON contains wrong attributes” }
Spinner