Die API lässt sich durch die Standards W3C SOAP und WSDL auf unterschiedlichen Plattformen verwenden und kann somit leicht in verschiedene Systeme integriert werden. Im Folgenden wird zunächst die Gestaltung und Nutzung der Schnittstelle und ihrer Parameter näher erläutert. Anschließend wird anhand konkreter Codebeispiele die Implementierung der API in verschiedenen gängigen Programmiersprachen veranschaulicht.
URL und Authentifizierung
Webservice URL
https://soap.epnic.net (OT&E: soap.ote.epnic.net)
WSDL URL
https://soap.epnic.net/dns_zone/?wsdl
Authentifizierung
Um Ihre Anfrage an das System zu authentifizieren, verwenden sie bitte den Benutzernamen und das Passwort, das Sie auch zur Anmeldung an Ihrem EPAG-Kundenaccount verwenden.
Abkürzungen und Begriffe
SSL
Die Abkürzung SSL steht für Secure Sockets Layer und ist ein Protokoll zur Verschlüsselung des Datenverkehrs auf TCP/IP-Ebene.
DNS
Das Domain Name System (DNS) ist einer der wichtigsten Dienste im Netzwerk. Seine Hauptaufgabe ist die Beantwortung von Anfragen zur Namensauflösung.
Zone
Im Domain Name System (DNS) des Internets bezeichnet die Zone den Teil des Domänenbaums, für die ein Nameserver (im Folgenden auch NS) zuständig ist und deshalb die offiziellen Daten kennt. Eine Zone wird durch einen Primary Nameserver verwaltet. Zur Erhöhung der Verfügbarkeit bei Server-Ausfällen ist es üblich, eine Zone auf einen oder mehrere Secondary Nameserver zu spiegeln.
WSDL
Die Web Services Description Language (WSDL) ist eine plattform-, programmiersprachen- und protokollunabhängige Beschreibungssprache für Netzwerkdienste (Webservices) zum Austausch von Nachrichten auf Basis von XML.
Introduction
Die hier dokumentierte Schnittstelle (API) dient zur Verwaltung von DNS-Zonen. Die Schnittstelle wird als Webservice auf SOAP-Basis angeboten.
Functions
Die API stellt derzeit die folgenden Funktionen zur Verfügung:
saveZone
DNS-Zone anlegen bzw. ändern.
deleteZone
DNS-Zone löschen.
getZones
Abrufen von Informationen aller „eigenen“ DNS-Zonen.
Error codes
Folgende Fehlercodes werden im Falle eines Fehlers für die Fehlerbeschreibung verwendet.
VAL001
Datenfeld nicht vorhanden.
VAL100
Datenfeld besitzt keinen Inhalt.
VAL101
Ungültiger Datentyp.
VAL102
Ungültiger Dateninhalt.
VAL103
Authentifizierung fehlgeschlagen.
VAL105
Zugriff auf Webservice verweigert (keine SSL-Verbindung).
VAL300
E-Mail Adresse besitzt kein gültiges Format.
VAL305
Datum oder Zeitraum ungültig.
VAL306
Ungültiger Domainname.
VAL307
Ungültige IPv4-Adresse
VAL308
Ungültiger Hostname.
VAL309
Ungültiger Resource Record.
VAL310
Ungültige Zeichenfolge.
VAL311
Kein primärer oder sekundärer Nameserver vorhanden.
VAL312
Doppelte Nameserver-Einträge vorhanden.
VAL313
Eigener Nameserver kann nicht verwendet werden.
VAL314
Nameserver nicht registriert.
VAL315
Ungültige Kombination von Resource Record-Einträgen.
VAL330
Ungültiger Zahlenwert.
VAL331
Ungültiger Wertebereich.
VAL340
Wert beinhaltet unerlaubte Zeichen.
VAL341
Resource Record: Kein „relativer“ Hostname.
VAL342
Resource Record: Keine gültige IPv4-Adresse.
VAL343
Resource Record: Keine gültige IPv6-Adresse.
VAL344
Resource Record: Ungültiger Wert für „MX-Priorität“.
VAL345
Resource Record: CNAME nicht erlaubt.
VAL346
Resource Record: NS-Records nur für Sub-Domains zugelassen.
VAL347
Resource Record: Keine Wildcard-Unterstützung für NS-Records.
VAL348
Resource Record: Erwartet gültigen Hostnamen anstelle von IP-Adresse.
VAL349
Resource Record: Kein gültiger Hostname.
VAL350
Resource Record: Ungültige URL.
VAL351
Resource Record: Keine Wildcard-Unterstützung für „redirect“.
VAL352
Resource Record: Validierung fehlgeschlagen.
DNS100
Unbekannter Fehler beim Anlegen der DNS-Zone.
DNS101
Unbekannter Fehler während „Update“ der DNS-Zone.
DNS102
Unbekannter Fehler beim Anlegen des „Resource Record“.
DNS200
Zugriff auf DNS-Zone verweigert.
DNS201
DNS-Zone existiert nicht.
DBA001
Datenbankfehler.
UNK001
Unbekannter oder unbehandelter Fehler.
saveZone
Über diese Funktion kann eine DNS-Zone angelegt werden bzw. können Daten einer vorhandenen DNS-Zone überschrieben werden. Die Daten einer Zone müssen dabei immer vollständig in einem Aufruf übergeben werden. Beim erfolgreichen Speichern werden existierende Daten einer Zone immer komplett überschrieben. Beachten Sie, dass für eine DNS-Zone mindestens zwei Namevserver (master + slave) definiert werden müssen (der erste Nameserver der angegeben wird, wird als „primärer“ Nameserver verwendet). Zudem muss bei einem NS-Eintrag das „host“-Feld leer sein.
Eingabeparameter
saveZone Eingabeparameter:
auth
yes
auth
Enthält die Daten zur Authentifizierung bei EPAG.
zone
yes
String
Name der Zone bzw. der Domain (z.B. „meineseite.de“).
hiddenPrimaryIP
optional
String
Soll ein verstecker primärer Nameserver verwendet werden, so tragen Sie an dieser Stelle bitte eine gültige IP (v4) ein.
records
yes
dnsRecord[]
Liste/Array mit Resource Record-Einträgen.
Datentyp auth:
username
yes
String
Benutzername des EPAG-Accounts.
password
yes
String
Passwort des EPAG-Accounts.
Datentyp dnsRecord:
host
yes
String
Relativer Hostname (z.B. „ftp“). Für einen NS-Eintrag muss dieses Feld leer sein!
type
yes
String
Resource Record-Typ. Mögliche Inhalte: NS, MX, A, AAAA, CNAME, TXT, PTR, http_redirect, frame_redirect oder http_redirect_permanent.
mxPriority
optional
String
Zahlenwert für MX-Priorität (0 = höchste Priorität). Nur für Typ „MX“.
value
yes
String
Resource-Data: Daten die den Resource Record näher beschreiben (zum Beispiel eine IP-Adresse für einen A-Eintrag, oder einen Hostnamen für einen NS-Eintrag).
Rückgabeparameter
saveZone Rückgabeparameter:
resultCode
Integer
Ergebnis-Code der Funktion.
1 = erfolgreich. -1 = gescheitert.
resultCount
Integer
Anzahl der in „result“ zurückgelieferten Ergebnisse.
result
String
Error code.
errorCount
String
Kurze Fehlerbeschreibung.
error
String[]
Liste/Array mit zusätzlichen Informationen (nur bei bestimmten Fehlern vorhanden).
See section "Error codes"
Datentyp error:
code
String
Error code.
See section "Error codes"
description
String
Kurze Fehlerbeschreibung.
parameters
String[]
Liste/Array mit zusätzlichen Informationen (nur bei bestimmten Fehlern vorhanden).
SOAP Beispiele
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:saveZone>
<body>
<auth>
<username>?</username>
<password>?</password>
</auth>
<zone>?</zone>
<hiddenPrimaryIP>?</hiddenPrimaryIP> <!-- optional -->
<records> <!-- one or more elements -->
<host>?</host> <!-- empty for ns-records -->
<type>?</type>
<mxPriority>?</mxPriority> <!-- only for mx/srv-records -->
<value>?</value>
</records>
<records>
<host>?</host>
<type>?</type>
<mxPriority>?</mxPriority>
<value>?</value>
</records>
</body>
</ns1:saveZone>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:saveZoneResponse>
<body>
<resultCode>?</resultCode> <-- success-code -->
<resultCount>?</resultCount> <-- number of result-elements -->
<result>?</result> <-- if resultCount greater 0 -->
<errorCount>?</errorCount> <-- number of error-elements -->
<error> <-- if errorCount greater 0 -->
<code>?</code>
<desc>?</desc>
<parameters> <-- zero, one or more elements -->
<name>a</name> <-- Param-Name -->
<value>b</value> <-- Param-Value -->
</parameters>
</error>
</body>
</ns1:saveZoneResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>deleteZone
Diese Funktion bietet die Möglichkeit eine DNS-Zone zu löschen. Da eine DNS-Zone nicht sofort gelöscht werden kann, wird diese vorerst nur als „gelöscht“ markiert. Das eigentliche Löschen erfolgt dann automatisch zu einem späteren Zeitpunkt.
Bitte beachten Sie, dass die Funktion getZones auch gelöscht-markierte Zonen zurückliefert, solange diese noch nicht endgültig gelöscht wurden.
Eingabeparameter
deleteZone Eingabeparameter:
auth
yes
auth. See section "saveZone".
Enthält die Daten zur Authentifizierung bei EPAG.
zone
yes
String
Name der Zone die gelöscht werden soll.
Rückgabeparameter
deleteZone Rückgabeparameter:
resultCode
Integer
Ergebnis-Code der Funktion.
1 = erfolgreich.
-1 = gescheitert.
resultCount
Integer
Anzahl der in „result“ zurückgelieferten Ergebnisse.
result
String
Kurze Erfolgsmeldung.
Die Rückgabe dieses Parameters erfolgt nur bei erfolgreicher Ausführung.
errorCount
Integer
Anzahl der zurückgelieferten Fehlermeldungen.
error
error. See section "Error codes".
Einzelne Fehlermeldung oder Liste mit Fehlermeldungen
(Die Rückgabe dieses Parameters erfolgt nur wenn
Fehler aufgetreten sind).
SOAP Beispiele
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:deleteZone>
<body>
<auth>
<username>?</username>
<password>?</password>
</auth>
<zone>?</zone>
</body>
</ns1:deleteZone>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:deleteZoneResponse>
<body>
<resultCode>?</resultCode> <-- success-code -->
<resultCount>?</resultCount> <-- number of result-elements -->
<result>?</result> <-- if resultCount greater 0 -->
<errorCount>?</errorCount> <-- number of error-elements -->
<error> <-- if errorCount greater 0 -->
<code>?</code>
<desc>?</desc>
<parameters> <-- zero, one or more elements -->
<name>a</name> <-- Param-Name -->
<value>b</value> <-- Param-Value -->
</parameters>
</error>
</body>
</ns1:deleteZoneResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>getZones
Diese Funktion liefert eine Liste mit den Daten aller DNS-Zonen, die dem eigenen Kunden-Account zugeordnet sind.
Um die Daten einer bestimmten Zone abzufragen, verwenden Sie bitte das Datenfeld „filter“.
Bitte beachten Sie dass die Funktion getZones auch als gelöscht-markierte Zonen zurückliefert, solange diese noch nicht endgültig gelöscht wurden.
Eingabeparameter
getZones Eingabeparameter:
auth
yes
auth. See section "saveZone".
Enthält die Daten zur Anmeldung bei EPAG.
filter
optional
getZonesFilter
Enthält die Kriterien, nach denen die Ausgabe gefiltert werden soll.
Datentyp getZonesFilter:
zone
optional
String
Es werden nur Daten zu der hier angegebenen Zone zurückgeliefert.
Rückgabeparameter
getZones Rückgabeparameter:
resultCode
Integer
Ergebnis-Code der Funktion.
1 = erfolgreich.
-1 = gescheitert.
resultCount
Integer
Anzahl der in „result“ zurückgelieferten Ergebnisse.
result
dnsZone[]
Liste /Array mit DNS-Zonen (resultCount = Anzahl der zurückgelieferten Elemente).
errorCount
Integer
Anzahl der zurückgelieferten Fehlermeldungen.
error
error. See section "Error codes".
Einzelne Fehlermeldung oder Liste mit Fehlermeldungen
(Die Rückgabe dieses Parameters erfolgt nur, wenn
Fehler aufgetreten sind).
Datentyp dnsZone:
zone
String
Beinhaltet Name der jeweiligen Zone.
hiddenPrimaryIP
String
IP des „versteckten“ primären Nameservers (sofern angegeben). Ansonsten leeres Datenfeld.
recordCount
Integer
Anzahl der Resource Records bzw. Elemente in record.
record
dnsZoneRecord[]
Liste /Array mit Resource Record-Einträgen.
Datentyp dnsZoneRecord:
host
String
Beinhaltet relativen Host-Namen.
Bei einem NS-Eintrag ist dieses Feld leer.
type
String
Beinhaltet Resource Record-Typ.
Mögliche Inhalte (je nach Benutzerberechtigung):
NS, MX, A, AAAA, CNAME, TXT, PTR, SRV, http_redirect, frame_redirect oder http_redirect_permanent.
mxPriority
String
Wert für MX/SRV-Priorität (0 = höchste Priorität).
value
String
Beinhaltet die Daten, die den Resource Record näher beschreiben (zum Beispiel eine IP-Adresse für einen A-Eintrag oder einen Hostnamen für einen NS-Eintrag).
SOAP Beispiele
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:getZones>
<body>
<auth>
<username>?</username>
<password>?</password>
</auth>
<filter> <!-- optional -->
<zone>?</zone>
</filter>
</body>
</ns1:getZones>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="epag.dns_zone">
<SOAP-ENV:Body>
<ns1:getZonesResponse>
<body>
<resultCode>?</resultCode> <-- success-code -->
<resultCount>?</resultCount> <-- number of result-elements -->
<result> <-- if resultCount greater 0 -->
<zone>?</zone>
<hiddenPrimaryIP>?</hiddenPrimaryIP>
<recordCount>?</recordCount> <!-- number of resource record-elements -->
<record> <!-- one or more elements -->
<host>?/host>
<type>?</type>
<mxPriority>?</mxPriority>
<value>?</value>
</record>
<record>
<host>?/host>
<type>?</type>
<mxPriority>?</mxPriority>
<value>?</value>
</record>
</result>
<errorCount>?</errorCount> <-- number of error-elements -->
<error> <-- if errorCount greater 0 -->
<code>?</code>
<desc>?</desc>
<parameters> <-- zero, one or more elements -->
<name>?</name> <-- Param-Name -->
<value>?</value> <-- Param-Value -->
</parameters>
</error>
</body>
</ns1:getZonesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>