URL and Authentication
Web Service URL
https://soap.epnic.net (OT&E: soap.ote.epnic.net)
WSDL URL
https://soap.epnic.net/dns_zone/?wsdl
Authentication
In order to authenticate your request to the system, please use the same username and password which you use to log into your EPAG customer account.
Terms and Abbreviations
SSL
The abbreviation SSL stands for Secure Sockets Layer and is a protocol for encoding data traffic on the TCP/IP level.
DNS
The Domain Name System (DNS) is one of the most important services in the network. Its main responsibility is to answer name resolution requests.
Zone
In the DNS of the internet, the Zone refers to the part of the domain tree for which a nameserver is responsible and therefore contains the official data. A Zone is administered by a Primary Nameserver. In order increase the amount of up-time in the case of a server outage, Zones are often mirrored on one or more Secondary Nameservers.
WSDL
The Web Services Description Language (WSDL) is a platform, programming language, and protocol-independent description language for web services used to exchange XML-based messages.
Introduction
The Interface (API) documented here can be used to manage DNS zones. The interface is offered as a Web Service based on SOAP.
Functions
The API currently supports the following functions:
saveZone
Create or change DNS zones.
deleteZone
Delete DNS zones.
getZones
Query information on all zones ou manage.
VAL001
Data field does not exist.
VAL100
Data field has no content.
VAL101
Invalid data type.
VAL102
Invalid data content.
VAL103
Authentication failed.
VAL105
Access to Web Service denied (no SSL connection).
VAL300
Email address is not formatted correctly.
VAL305
Invalid date or time period.
VAL306
Invalid domain name.
VAL307
Invalid IPv4 Address.
VAL308
Invalid host name.
VAL309
Invalid Resource Record.
VAL310
Invalid character string.
VAL311
No primary or secondary nameserver present.
VAL312
Duplicate nameserver entry exists.
VAL313
Private nameservers cannot be used.
VAL314
Nameserver not registered.
VAL315
Invalid combination of Resource Record entries.
VAL330
Invalid numeric value.
VAL331
Invalid value range.
VAL340
Value containts illegal characters.
VAL341
Resource Record: No „relative“ host name.
VAL342
Resource Record: No valid IPv4 Address.
VAL343
Resource Record: No valid IPv6 Address.
VAL344
Resource Record: <invalid value for „MX Priority“.
VAL345
Resource Record: CNAME not allowed.
VAL346
Resource Record: nameserver records only allowed for subdomains.
VAL347
Resource Record: Wildcards not supported for nameserver records.
VAL348
Resource Record: Valid host name expected instead of IP Address.
VAL349
Resource Record: No valid host name.
VAL350
Resource Record: Invalid URL.
VAL351
Resource Record: No Wildcards supported for „redirect“.
VAL352
Resource Record: Validation failed.
DNS100
Unknown error during the creation of the DNS zone.
DNS101
Unknown error during the update of the DNS zone.
DNS102
Unknown error during the creation of the Resource Record.
DNS200
Access to the DNS zone denied.
DNS201
DNS zone does not exist.
DBA001
Database error.
UNK001
Unknown or unhandled error.
saveZone
This function allows you to either create a new DNS zone or to overwrite an existing DNS zone. The data for a zone must always be provided in entirety in the call. When successfully saved, the existing data from a zone will be completely overwritten. Please note that two nameservers (master and slave) must always be given for a DNS zone. The first nameserver given will be considered the primary nameserver. In addition, the "host" field must be empty in a nameserver entry.
Input parameters
saveZone input parameters:
auth
yes
auth
Contains the data to be authenticated by EPAG.
zone
yes
String
Name of the zone or domain name (e.g.. "meineseite.de“).
hiddenPrimaryIP
optional
String
If a hidden primary server is being used, you can enter a valid IP Address (Ipv4) here.
records
yes
dnsRecord[]
List/Array with Resource Record entries.
Data type auth:
username
yes
String
Username of the EPAG account.
password
yes
String
Password of the EPAG account.
Data type dnsRecord:
host
yes
String
Relative host name (e.g. „ftp“). This field must be empty for a nameserver entry.
type
yes
String
Resource Record type.
Allowed content: NS, MX, A, AAAA, CNAME, TXT, PTR, http_redirect, frame_redirect or http_redirect_permanent.
mxPriority
optional
String
Numeric value for MX Priority (0 = highest priority). Only for type "MX“.
value
yes
String
Resource data: Data describing the Resource Record (for example an IP Address for an A record or a host name for a nameserver entry).
Return parameters
saveZone return parameters:
resultCode
Integer
Result code of the function.
1 = successful.
-1 = failed.
resultCount
Integer
Count of the returned results in the "result“ parameter.
result
String
Error code.
errorCount
String
Short error description.
error
String[]
List/Array with additional information (only available for certain errors).
See section "Error codes"
Data type error:
code
String
Error code.
See section "Error codes"
description
String
Short error description.
parameters
String[]
List/Array with additional information (only available for certain errors).
SOAP Examples
<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
This function allows you to delete DNS zones. Since a DNS zone cannot be deleted immediately, it will first be marked as deleted. The actual deletion of the zone will later be processed automatically.
Please note that the getZones function will also return zones that have been marked for deletion as long as the actual deletion has not yet been processed.
Input parameters
deleteZone input parameters:
auth
yes
auth. See section "saveZone".
Contains the data to be authenticated by EPAG.
zone
yes
String
Name of the zone to be deleted.
Return parameters
deleteZone return parameters:
resultCode
Integer
Result code of the function
1 = successful.
-1 = failed.
resultCount
Integer
Count of the returned results in the "result“ parameter.
result
String
Short success message. This message is returned only after successful completion.
errorCount
Integer
Count of the returned error messages.
error
error. See section "Error codes".
Individual error messages or a list of error messages. This result is only returned when errors occur.
SOAP Examples
<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
This function returns a list of the data of all DNS zones corresponding to your customer account.
In order to retrieve the data of a specific zone, please use the data field "filter." Please note that the getZones function also returns zones that are marked for deleton as long as these zones have not actually been deleted.
Input parameters
getZones input parameters:
auth
yes
auth. See section "saveZone".
Contains the data to be authenticated by EPAG.
filter
optional
getZonesFilter
Contains the criteriae to be used to filter results.
Data type getZonesFilter:
zone
optional
String
Only data for the given zone will be returned.
Return parameters
getZones return parameters:
resultCode
Integer
Result code of the function.
1 = successful.
-1 = failed.
resultCount
Integer
Count of the returned results in the "result“ parameter.
result
dnsZone[]
List/Array with DNS zones.
errorCount
Integer
Count of the returned error messages.
error
error. See section "Error codes".
Individual error messages or a list of error messages. This result is only returned when errors occur.
Data type dnsZone:
zone
String
Contains the name of the respective zone.
hiddenPrimaryIP
String
IP Address of the "hidden" primary nameserver, where given. Otherwise an empty data field.
recordCount
Integer
Count of the Resource Records or elements in the record.
record
dnsZoneRecord[]
List/Array with Resource Record entries.
Data type dnsZoneRecord:
host
String
Contains the relative host names. This field will be empty for a namserver entry.
type
String
Contains the Resource Record type. Possible content (according to user permissions): NS, MX, A, AAAA, CNAME, TXT, PTR, SRV, http_redirect, frame_redirect or http_redirect_permanent.
mxPriority
String
Value for MX/SRV Priority (0 = highest priority).
value
String
Resource data: Data describing the Resource Record (for example an IP Address for an A record or a host name for a nameserver entry).
SOAP Examples
<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>