easyname API

Easyname stellt für professionelle und kommerzielle Nutzer eine API zur Verfügung, mit der alles Rund um eine Domain über eine Schnittstelle geregelt werden kann. So kann Easyname in eigene Software und Controlpanels integriert werden.

                                                       ___    ____  ____
  ___  ____ ________  ______  ____ _____ ___  ___     /   |  / __ \/  _/
 / _ \/ __ `/ ___/ / / / __ \/ __ `/ __ `__ \/ _ \   / /| | / /_/ // /
/  __/ /_/ (__  ) /_/ / / / / /_/ / / / / / /  __/  / ___ |/ ____// /
\___/\__,_/____/\__, /_/ /_/\__,_/_/ /_/ /_/\___/  /_/  |_/_/   /___/
               /____/

Auf den folgenden Seiten finden sich die technische Dokumentation zur API, sowie nützliche Informationen zu einzelnen Kommandos. Sollten weitere Fragen oder technische Probleme bei der Integration der API auftreten, so kontaktiere bitte den Support.

REST Basics

Die API basiert grundsätzlich auf dem Konzept von REST Web Serivces. So werden einzelne Resourcen (Domain, Contact, Emailbox, …) definiert und auf diese Operationen ausgeführt. Über die Kombination HTTP Request Method + URI werden die Resourcen und Operationen angesprochen.

Die API ist unter folgendem Hostnamen ausschließlich per HTTPS zu erreichen: api.easyname.com

Entsprechend dem Konzept von REST Web Services sind die URIs in Kombination mit der HTTP Request Method wie folgt aufgebaut.

HTTP Request Method GET

Liste der Resource-Elemente

GET /<resource>

Beispiel:

GET /domain?limit=50&offset=200

Listet alle Elemente einer Resource auf. Es werden max. 50 Elemente zurück gegeben. Für die Auflistung weiterer Elemente sind die optionalen Parameter limit und offset zu benutzen. Optionale Parameter:

• limit
• offset

Einzelnes Resource-Element

Gibt das durch spezifizierte Element der Resource zurück.

GET /<resource>/<id>

HTTP Request Method POST

Neue Resource erstellen

POST /<resource>

Erstellt eine neue Resource

Bestehende Resource updaten (allgemein)

POST /<resource>/<id>

Updated das durch spezifizierte Element der Resource Kann optional auch mit der HTTP Request Method PUT ausgeführt werden.

Spezielle Operation auf bestehende Resource ausführen

POST /<resource>/<id>/<perform-command>

Updated das durch spezifizierte Element der Resource, führt dabei aber kein gewöhnliches Update aus, sondern es wird dabei das in spezifizierte Command ausgeführt. Kann optional auch mit der HTTP Request Method PUT ausgeführt werden.

HTTP Request Method DELETE

Diese Request Method wird nicht unterstützt. Sollte ein Element einer Resource löschbar sein, so wird dies explizit bei der Resource beschrieben.

Request / Response

Alle Anfragen, die mittels POST gestellt werden, müssen im HTTP_RAW_DATA_POST einen Body übermitteln. Dieser Body darf ausschließlich einen JSON-encoded String enthalten, der im folgenden beschrieben wird.

Aufbau des Body (allgemein)

Der JSON-encoded String hat folgende Struktur:

{
  "data": {
      "<key>": "<value>",
      ...
  },
  "timestamp": 1234567890,
  "signature": "<signature>"
}

Der timestamp ist ein UNIX-Timestamp und muss der aktuellen Zeit in UTC entsprechen.

Berechnung der Signatur

Beispiel

Signing-Salt:

SuperSecretSigningSalt

Daten:

{
  "data": {
    "id": 1234,
    "domain": "example.com",
    "expire": "2015-03-05",
    "trustee": false,
    "purchased": "2010-03-05"
  },
  "timestamp": 1234567890,
  "signature": "<signature>"
}

Daraus ergibt sich folgende Sortierung der Keys:

domain, expire, id, purchased, timestamp, trustee

und folgender String nach aneinanderfügen der Werte und den String teilen:

example.com 2015-03-05 123420 10-03-05 1234567890
example.com 2015-03-05 123420 10-03-05 1234567890

Um die Authentizität der Daten zu gewährleisten, hat jede Anfrage, die mittels POST oder PUT gestellt wird, eine Signatur zu beinhalten. Diese Signatur wird wie folgt berechnet.

• Alle Keys aus data einschließlich des Timestamps müssen in aufsteigender Reihenfolge sortiert werden. Bei Listen ist zusätzlich auf die Reihenfolge der Elemente in der Liste zu achten!
• Anhand dieser Sortierung sind alle Werte der Keys aneinander zu fügen
• Dieser String ist in der Hälfte zu teilen (bei ungerader Zeichenanzahl: Länge + 1)
• Zwischen den beiden Hälften ist der zur Verfügung gestellte Signing-Salt einzufügen
• Daraus ist ein MD5-Hash zu bilden, welcher Base64-encoded an den Request anzufügen ist

Folgender String muss nun zuerst MD5-gehasht und danach Base64-encodet werden:

example.com 2015-03-05 12SuperSecretSigningSalt34 2010-03-05 1234567890

Der ergibt folgende Signatur, die dann mitgeschickt werden muss:

NDQ3ZWM3NWVlYzkwY2UxZDdkNjNiMzk4ZmNkYmRiOGY=

Beispiel 2 Daten:

{
  "data": [
    {
      "id": 1234,
      "domain": "example.com",
      "expire": "2015-03-05",
      "trustee": false,
      "purchased": "2010-03-05"
    },
    {
      "id": 2548,
      "domain": "foo.at",
      "expire": "2013-04-09",
      "trustee": false,
      "purchased": "2011-04-09"
    },
    {
      "id": 3658,
      "domain": "bar.de",
      "expire": "2013-08-08",
      "trustee": true,
      "purchased": "2010-08-08"
    }
  ],
  "timestamp": 1234567890,
  "signature": "<signature>"
}

Daraus ergibt sich folgende Sortierung der Keys:

domain, expire, id, purchased, trustee, domain, expire, id, purchased, trustee, domain, expire, id, purchased, trustee, timestamp

und folgender String nach aneinanderfügen der Werte:

example.com 2015-03-05 123420 10-03-05 foo.at 2013-04-09 254820 11-04-09 bar.de 2013-08-08 3658 2010-08-08 11234567890

Die weitere Vorgehensweise entspricht dem vorangehenden Beispiel. Das Ergebnis ist folgende Signatur:

NGRmNmUwZDkwNzc0M2JiNzc0ZjEyOWE1NmE3ZTdjZDQ=

Aufbau des Antwort-Body

{
  "data": {
    "<key>": "<value>",
    ...
  },
  "status": {
    "type": "(success|pending|warning|error|systemerror)",
    "code": <return-code|error-code>,
    "message": "<message>"
  }
  "timestamp": 1234567890,
  "signature": "<signature>"
}

Der Antwort-Body entspricht weitesgehendst dem allgemeinen Body, es wird jedoch eine Statusinformation zur ausgeführten Anfrage hinzugefügt.

Es wird empfohlen die Signatur der Antwort zu verifizieren.

Statusinformationen fließen nicht in die Signatur mit ein.

HTTP Status Codes

Es entspricht dem Konzept des RESTful Web Service, dass die vorhandenen HTTP Status Codes genutzt werden, um den Status der Anfrage mitzuteilen. Da Easyname jedoch ein sehr komplexes System ist, dienen die HTTP Status Codes nur dazu, den allgemeinen Status einer Anfrage mitzuteilen. Der genaue Status der Anfrage ist, wie bereits erwähnt, dem Antwort-Body zu entnehmen.

Folgende Status Codes werden verwendet:

• 200 OK: Der Auftrag wurde entgegen genommen und bereits verarbeitet.
• 202 Accepted: Der Auftrag wurde entgegen genommen und wurde zur weiteren Verarbeitung eingereiht bzw- zur weiteren Verarbeitung an externe Stellen (z.B. Domainregistry) übermittelt.
• 400 Bad Request: Die Anfrage an sich ist fehlerhaft. Dieser Fehler schließt auch Validierungsfehler mit ein!
• 404 Page Not Found: die verwendete URL/URI ist nicht gültig.
• 500 Internal Server Error: Bei der Verarbeitung ist ein unerwarteter Fehler aufgetreten. Der Fehler wurde entsprechend protokolliert und an das Entwicklungs-Team weiter gegeben.
• 503 Service unavailable: Das Anfrage-Limit pro Minute/Stunde/Tag wurde überschritten oder die API steht derzeit wegen Wartungsarbeiten nicht zur Verfügung (bitte beachten Sie entsprechende Ankündigungen)

Authentifizierung

Die Authentifizierung für die Benutzung der API erfolgt mittels HTTP Headern.

Header

Folgende Header sind erforderlich:

X-User-ApiKey:
X-User-Authentication:
Accept: application/json

X-User-ApiKey

Beispiel:

User-ID: 123
Email: support@easyname.eu
Signing123TopSecretsupport@easyname.euAuth00

Der von Easyname vergebene API-Key ist immer im Header mitzuschicken. Ohne diesen API-Key kann keine Authentifizierung stattfinden.

X-User-Authentication

Um zu verifizieren ob die Anfrage auch tatsächlich von dem Inhaber des API-Keys stammt, ist für jede Anfrage ein Authentication-String zu generieren und mit zu senden.

Für die Authentifizierung wird ein eigenes Salt zur Verfügung gestellt, welches 2 Marker besitzt, die ersetzt werden müssen.

Beispiel: Signing%sTopSecret%sAuth00

Das erste %s muss durch die User-ID ersetzt werden, das zweite %s muss durch die Emailadresse ersetzt werden.

Aus diesem String ist nun ein MD5-Hash zu bilden, welcher Base64-encoded im Header X-User-Authentication mit zu schicken ist.

Status Codes

Status Codes liefern mittels eines fünfstelligen, nummerischen Wertes den Status des ausgeführten Kommandos zurück. Auch Fehler werden als Status Code abgebildet.

Grundsätzlich können Status Codes in fünf Gruppen eingeteilt werden:

• Success (1xxxx)
• Pending (2xxxx)
• Warning (3xxxx)
• Error (6xxxx)
• Systemerror (7xxxx)

Eine Übersicht über alle Status- und Errorcodes finden sich hier.

PHP-SDK

Easyname REST API client sample usage

Get the easyname php-sdk: github repo

Create a config file with your credentials

# config.php
<?
return array(
    'url' => 'https://api.easyname.com',
    'user' => array(
        'id' => 0,
        'email' => 'foo@example.org'
    ),
    'api' => array(
        'key' => 'aaaaaaa',
        'authentication-salt' => 'aaaaaaaa%sbbbbbbbb%scccccccc',
        'signing-salt' => 'AaaBbbCccDddEeeFffGggHhh'
    ),
    'debug' => true,
);

Instantiate the client and call one of the methods it provides

<?php
/**
 * Easyname REST API client sample usage.
 *
 * @copyright  2006-2021 easyname GmbH (http://www.easyname.com)
 * @license    easyname License Agreement
 */

ini_set('date.timezone', 'UTC');

require_once 'src/Easyname/RestApi/Client.php';
require_once 'src/Easyname/RestApi/Exception.php';

$result = null;
$api = new \Easyname\RestApi\Client(
    include 'config.php'
);
/*
 * Domain
 */
$result = $api->listDomain();
//$result = $api->getDomain(1);
//$result = $api->createDomain("example.com", 23, 23, 23, 23, array(), false);
//$result = $api->transferDomain("example.com", 23, 23, 23, 23, array(), false, 'aaaaaa');
//$result = $api->changeOwnerOfDomain(1, 23);
//$result = $api->changeContactOfDomain(1, 23, 23, 23);
//$result = $api->changeNameserverOfDomain(1, array('ns1.example.com', 'ns2.example.com'));
//$result = $api->expireDomain(1);
//$result = $api->unexpireDomain(1);
//$result = $api->deleteDomain(1);
//$result = $api->restoreDomain(1);

/*
 * Contact
 */
//$result = $api->listContact();
//$result = $api->getContact(1);
//$result = $api->createContact('person', 'John Doe (person)', 'John Doe', 'Street 12/34', '1234', 'Vienna', 'AT', '+4312345678', 'me@example.com', array('birthday' => '1970-01-31'));
//$result = $api->updateContact(1, 'John Doe (person)', 'Other Street 56/7', '1234', 'Vienna', '+4312345678', 'me@example.com', array('birthplaceCity' => 'Vienna'));
//$result = $api->deleteContact(1);

var_dump($result);

Domain

Die Domain-Resource bildet die Registrierung, den Transfer sowie die gesamte Verwaltung einer Domain ab. Es ist dabei zu beachten, das unterschiedliche Topleveldomains teilweise Kommandos nicht unterstützen oder z.B. andere Fristen (z.B. für die Kündigung) haben. Auch das Verhalten von unterschiedlichen Topleveldomains in bestimmten Situationen kann abweichen.

Domain Generate Authcode

POST /domain/<id>/generateauthcode

Generiert einen Authcode für eine Domain und sendet diesen zur Registry. Der generierte Authcode hat eine Lebensdauer (siehe Domain -> authcodeValidUntil). Nach erreichen der Lebensdauer ist der Authcode nicht mehr gültig und muss neu generiert werden. Während der Lebensdauer kann kein neuer Authcode generiert werden.

Input

Es werden keine Inputdaten benötigt

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Transfersecurity

POST /domain/<id>/transfersecurity

Setzt bzw. hebt eine Transfersperre wieder auf. Die Transfersperre verhindert, das die Domain zu einem anderen Registrar/Provider transferiert werden kann.

Input

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Restore

POST /domain/<id>/restore

Ein Domain Restore kann derzeit nur für .at-Domains (inkl. .co.at, .or.at) ausgeführt werden. Er holt eine Domain, die im Zuge einer versäumten Verlängerung an die zuständige Registrierungsstelle zurück gegeben wurden, wieder von dieser zurück zu Easyname.

Input

Es werden keine Inputdaten benötigt

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Ownerchange

POST /domain/<id>/ownerchange

Der Inhaberwechsel, auch Ownerchange genannt, wechselt, wie der Name schon sagt, den Inhaber einer Domain.

Ein Inhaberwechsel kann nur durchgeführt werden, wenn:

• Die Topleveldomain einen Inhaberwechsel unterstützt
• Der neue Kontakt ggf. zusätzliche Daten lt. Vorgaben der Topleveldomain aufweist
• Der neue Kontakt die Restriktionen der Topleveldomain erfüllt

Ein Trustee kann derzeit im Zuge eines Ownerchanges nicht bestellt/abbestellt werden.

Input

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Nameserverchange

POST /domain/<id>/nameserverchange

Ändert die Nameserver einer Domain.

Die Nameserver können nur geändert werden, wenn:

• Die Domain keine sonstigen ausstehenden Updates hat
• Die Nameserver vom Hostnamen her unique sind
• Die Nameserver aufgelöst werden können
• Die Nameserver von der IP-Adresse her unique sind
• Die min./max. Nameservers den Vorgaben der Topleveldomain entsprechen
• Alle Kontakte ggf. zusätzliche Daten lt. Vorgaben der Topleveldomain aufweisen
• Alle Kontakte die Restriktionen der Topleveldomain erfüllen

Input

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Index

GET /domain

Holt eine Liste aller aktiven Domains.

Output

Domain Get

GET /domain/<id>

Holt das über spezifizierte Domain-Objekt.

Output

Domain Unexpire

POST /domain/<id>/unexpire

Holt eine Domain wieder aus dem Status EXPIRE heraus.

Input

Es werden keine Inputdaten benötigt

Output

Domain Expire

POST /domain/<id>/expire

Setzt eine Domain auf den Status EXPIRE, d.h. mit Ende der Registrierungszeit wird die Domain gelöscht.

Input

Es werden keine Inputdaten benötigt

Output

Domain Delete

POST /domain/<id>/delete

Löscht eine Domain bei der zuständigen Registrierungsstelle.

Input

Es werden keine Inputdaten benötigt

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Contactchange

POST /domain/<id>/contactchange

Ein Contactchange, auch Handlechange genannt, werden die Kontakte für Admin-C, Tech-C und Zone-C ausgetauscht. Sollte der Inhaber getauscht werden, so ist ein Inhaberwechsel (Ownerchange) durchzuführen.

Durchführbar ist ein Contactchange nur dann, wenn

• die Topleveldomain dies unterstützt
• alle Kontakte ggf. zusätzliche Daten lt. Vorgaben der Topleveldomain aufweisen
• alle Kontakte die Restriktionen der Topleveldomain erfüllen
• jeder einzelne Kontakt keine ausständigen Updates mehr hat
• die Domain keine ausständigen Updates mehr hat

Ein Trustee kann derzeit im Zuge eines Contactchanges nicht bestellt/abbestellt werden.

Input

Output

Es werden keine Daten zurück gegeben, sondern lediglich eine Statusmeldung

Domain Autorenew

POST /domain/<id>/autorenew

Aktiviert/deaktiviert die automatische Verlängerung einer Domain. Wird eine Domain nicht automatisch verlängert, so ist die Verlängerung manuell durchzuführen. Wird keine Verlängerung durchgeführt, so wird die Domain je nach Topleveldomain gelöscht oder an die zuständige Registrierungsstelle zurück gegeben.

Input

Output

Domain Create/Transfer

POST /domain

Das Erstellen einer Domain entspricht einer Neuregistrierung. Sollte ein Transfer der Domain von einem anderen Provider zu Easyname gewünscht sein, so ist das entsprechende Flag und ggf. der AuthCode zu setzen!

Eine Domain kann nur dann registriert/transferiert werden, wenn:

• Die Topleveldomain von Easyname unterstützt wird
• Der Domainname entsprechend den Vorgaben (min./max. Länge, IDN) der Topleveldomain gültig ist
• Ggf. angegebene Nameserver korrekt sind (Details siehe Nameserver Change)
• Alle Kontakte ggf. zusätzliche Daten lt. Vorgaben der Topleveldomain aufweisen
• Alle Kontakte die Restriktionen der Topleveldomain erfüllen oder ein Trustee aktiviert wurde (sofern verfügbar)

Input

Contact

Kontakte (oftmals auch als Handles bezeichnet), dienen dazu, eine Domain einer Person/Organisation zu zuweisen (Inhaber) sowie spezielle Kontakttypen wie z.B. Admin-C, Tech-C, Zone-C für eine Domain zu benennen.

Ein Kontakt kann für beliebig viele Domains und Einsatzzwecke (Owner-C, Admin-C, Tech-C, Zone-C) verwendet werden. Kontakte können unabhängig von Domains erstellt und bearbeitet werden. Ist ein Kontakt jedoch mit einer/mehrere Domains verknüpft, so scheinen nach einem Update im Whois der Domain die geänderten Daten auf.

Contact Index

GET /contact

Liefert eine Liste mit allen verfügbaren Contacts zurück.

Output

Contact Get

GET /contact/<id>

Holt das über spezifizierte Contact-Objekt.

Output

Contact Create

POST /contact

Erstellt einen Contact, der in weiterer Folge Domains zugewiesen werden kann.

Input

Output

User

Der User entspricht dem Easyname-Konto.

User Balance

POST /user/<id>/balance

Liefert den aktuellen Kontostand und Währung zurück.