Atomia DNS API is used to create, edit and delete zone data in the Atomia DNS system. All changes done through the API will be provisioned to the nameservers that are configured in the system.
You connect to the SOAP API by using the SOAP endpoint
hostname.of.your.soap.server /atomiadns
.
The URI of the namespace should be urn:Atomia::DNS::Server.
All methods either succeed or return a SOAP Fault.
The faults are categorized into one of three groups:
LogicalError: Data is syntactically valid, but not semantically. An example is violation of a unique-constraint.
InvalidParametersError: Data doesn't have valid syntax
SystemError: Error in the communication with the database
InternalError: These errors should not occur, and should be reported as bugs
In addition users of the DNS SOAP API will have to deal with the possibility of transport errors between the client and the SOAP Server.
The current list of thrown exceptions are:
|
Exception |
Description |
|
InternalError.UnknownException |
This means that an error occured that was not handled by the application. This should not happen. |
|
InvalidParametersError.Bad* |
This means that some parameter had an invalid format. The exception type differs based on the parameter name, like InvalidParametersError.Badresourcerecordlabel. |
|
InvalidParametersError.BadArray |
An array parameter was badly formed. |
|
InvalidParametersError.BadChangeStatus |
Thrown when trying to update a change-row to something other than OK or ERROR. |
|
InvalidParametersError.BadNumberOfParameters |
Thrown when the number of parameters to a method-call is wrong. |
|
InvalidParametersError.BadRdataFor |
This is thrown when the format of the rdata for a record is bad. The validation-rules can be found in the table allowed_type in the DNS database. |
|
InvalidParametersError.BadType |
The record had a type not allowed. The list of allowed types can be found in the table allowed_type in the DNS database. |
|
InvalidParametersError.Soa |
The format of the SOA-record was bad. |
|
LogicalError.CNAMEAndOtherData |
Thrown when your modification would have meant that a label in some zone got a CNAME-record together with some other record, which is not allowed. |
|
LogicalError.CrossObjectMove |
Thrown when you try to move records cross labels or labels cross zones. This is not supported, instead you add and delete. |
|
LogicalError.DifferentTTLForSameLabelClassAndType |
Thrown when your modification would mean that some label got two records in the same class with different TTL:s, which is not allowed. |
|
LogicalError.EmptyLabel |
This should not occur, but means that the database server didn't accept the change because a label in the database was modified to not having any records (it should be deleted in this case). |
|
LogicalError.RecordNotFound |
A record that the method tried to access was not found. |
|
LogicalError.SameSourceAndDestination |
This is thrown when trying to do bulk operations with the same source and destination. |
|
LogicalError.Uniqueness |
This is thrown when trying to add an object which already exists (most often a zone). |
|
LogicalError.ZoneNotFound |
This is thrown when trying to administer a zone which doesn't exist. |
|
LogicalError.ZoneRequiredRecords |
This is thrown if your modification would mean that the zone didn't have a SOA and at least one NS-record. |
|
SystemError.DatabaseBadResult |
This means that there was an error fetching data from or updating data in the database. |
|
SystemError.DatabaseConnection |
This means that there was an error when connecting to the database. |
|
SystemError.PreparingStatement |
This means that there was an error preparing a statement used to access the database. |
Besides the standard SOAP Data types, the following types are returned by some methods:
resourcerecord is a struct with the following members:
Parameter | Type | Description |
| id | int | the id of the record |
| label | string | the label of the record |
| class | string | the DNS class, almost always IN |
| ttl | int | the time in seconds which it is valid to cache the record for |
| type | string | the DNS type of the record |
| rdata | string | the data of the record, an example for MX would be '10 mailserver.acompany.com.' |
hostname is a struct with the following members:
Parameter | Type | Description |
| zone | string | the name of the zone |
| label | string | the name of the label |
zonemetadata is a struct with the following members:
Parameter | Type | Description |
| key | string | the metadata key |
| value | string | the metadata value |
label is a struct with the following members:
Parameter | Type | Description |
| name | string | the name of the label |
| records | resourcerecord[] | an array of resourcerecords |
findresponse is a struct with the following members:
Parameter | Type | Description |
| total | int | the number of zones matching the query |
| zones | string[] | the zone names |
slavezones is an array of slavezone-structs.
slavezone is a struct with the following members:
Parameter | Type | Description |
| name | string | the name of the slave zone |
| master | string | the ip-address of the master |
zonestruct is a struct with the following members:
Parameter | Type | Description |
| id | int | id of the zone |
| name | string | name of the zone |
zones is an array of zonestruct-structs.
changedzone is a struct with the following members:
Parameter | Type | Description |
| id | int | the id of the change-row |
| name | string | the name of the zone this change-row applies to |
| changetime | int | he unix timestamp of this change (will be used as serial in SOA) |
changes is an array of changedzone-structs.
allowedtransfer is a struct with the following members:
Parameter | Type | Description |
| zonename | string | the name of the zone for which transfers are allowed, or * to allow for all zones |
| allowed_ip | string | the IP to allow transfers from |
allowedtransfers is an array of allowedtransfer-structs.
binaryzone is a struct with the following members:
Parameter | Type | Description |
| name | string | the name of the zone |
| binaryzone | string | a string representation of the zone, will be sent base64 encoded |
binaryzones is an array of binaryzone-structs.
keyset is a struct with the following members:
Parameter | Type | Description |
| id | int | the id of the key |
| algorithm | string | the algorithm of the key |
| activated | int | 0 if the key is inactive and 1 if it is active |
| keysize | int | the size of the key in bits |
| keytype | string | ZSK or KSK |
| activated_at | string | the date of the key activation or empty if not activated |
| deactivated_at | string | the date of the key deactivation or empty if not deactivated |
| keydata | string | the private key in Private-key-format v1.2 |
ds_set is a struct with the following members:
Parameter | Type | Description |
| digest | string | the digest of a KSK as defined in the RR format of a DS record |
| digestType | int | the digest algorithm used to create the digest, as defined in the RR format of a DS record |
| alg | int | the algorithm value of the KSK DNSKEY record that this digest applies to |
| keyTag | int | the keytag of the KSK DNSKEY record that this digest applies to |
external_keyset is a struct with the following members:
Parameter | Type | Description |
| id | int | the id of the key |
| keydata | string | the key in DNSKEY RR format |
zskinfo is a struct with the following members:
Parameter | Type | Description |
| id | int | the id of the key |
| activated | int | 0 if the key is inactive and 1 if it is active |
| created_at | string | the date of the key creation |
| activated_at | string | the date of the key activation or empty if not activated |
| deactivated_at | string | the date of the key deactivation or empty if not deactivated |
| created_ago_seconds | int | the number of seconds since the key creation |
| deactivated_ago_seconds | int | the number of seconds since the key deactivation |
| max_ttl | int | the maximum TTL of all records in this instance of Atomia DNS |
Add a zone to the Atomia DNS master database.
void AddZone( string zonename, int zonettl, string mname, string rname, int refresh, int retry, int expire, int minimum, string[] nameservers, string nameservergroup )
Parameter | Type | Description |
| zonename | string | the name of the zone |
| zonettl | int | the ttl of the SOA-record and the NS-records |
| mname | string | the SOA mname field |
| rname | string | the SOA rname field |
| refresh | int | the SOA refresh field |
| retry | int | the SOA retry field |
| expire | int | the SOA expire field |
| minimum | int | the SOA minimum field |
| nameservers | string[] | an array of the hostnames of the nameservers for the zone |
| nameservergroup | string | the nameserver group that should host the zone |
Deletes a zone from the database.
Edits a zone. This is only for completeness, and could be done by editing the SOA and NS-records directly as well.
void EditZone( string zonename, int zonettl, string mname, string rname, int refresh, int retry, int expire, int minimum, string[] nameservers, string nameservergroup )
Parameter | Type | Description |
| zonename | string | the name of the zone |
| zonettl | int | the ttl of the SOA-record and the NS-records |
| mname | string | the SOA mname field |
| rname | string | the SOA rname field |
| refresh | int | the SOA refresh field |
| retry | int | the SOA retry field |
| expire | int | the SOA expire field |
| minimum | int | the SOA minimum field |
| nameservers | string[] | an array of the hostnames of the nameservers for the added zone |
| nameservergroup | string | the nameserver group that should host the zone |
Adds a list of records to a zone.
int[] AddDnsRecords( string zonename, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Changes a list of records in a zone.
void EditDnsRecords( string zonename, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Sets the records for all matching label/type/class-triples in a zone to that specified by the records passed.
void SetDnsRecords( string zonename, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Deletes a list of records from a zone.
void DeleteDnsRecords( string zonename, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Fetches a list of all records for a specified zone and label.
[resourcerecord|resourcerecord Datatype - Atomia DNS API][] GetDnsRecords( string zonename, string label )
Fetches a list of all labels for a specified zone.
Fetches a complete zone from the database.
Fetches a list of complete zones from the database.
[binaryzones|binaryzones Datatype - Atomia DNS API] GetZoneBulk( string[] zones )
Fetches all metadata for a zone.
[zonemetadata|zonemetadata Datatype - Atomia DNS API][] GetZoneMetadata( string zonename )
Sets all metadata for a zone.
void SetZoneMetadata( string zonename, string[] keys, string[] values )
Restore a complete zone (or just set all records for some other reason).
void RestoreZone( string zonename, string nameservergroup, [zone|zone Datatype - Atomia DNS API] zone )
Restore a complete zone (or just set all records for some other reason).
void RestoreZoneBinary( string zonename, string nameservergroup, string zone )
Restore several complete zones (or just set all records for some other reason).
void RestoreZoneBulk( string[] zonenames, string nameservergroup, string[] zones )
Sets the records for all matching label/type/class-triples in a list of zones to that specified by the records passed.
void SetDnsRecordsBulk( string[] zones, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Copies a complete zone to one or more other zones, overwriting any preexisting data.
Copies all records from a label in the source zone to the same label in one or more other zones, overwriting any preexisting data.
void CopyDnsLabelBulk( string sourcezone, string label, [hostname|hostname Datatype - Atomia DNS API][] destinationzones )
Deletes all matching records from a list of zones. Everything except id must match for a record to be deleted.
void DeleteDnsRecordsBulk( string[] zones, [resourcerecord|resourcerecord Datatype - Atomia DNS API][] records )
Add a nameserver as a subscriber of changes to the data set in this server.
Remove a nameserver as a subscriber of changes to the data set in this server.
Gets the group name that a nameserver is configured as a subscriber for.
Fetches a list of all changed zones for a nameserver.
[changes|changes Datatype - Atomia DNS API] GetChangedZones( string nameserver )
Fetches a list of all changed zones for a nameserver, but limit response to a number of changes.
[changes|changes Datatype - Atomia DNS API] GetChangedZonesBatch( string nameserver, int num )
Mark a change-row as handled, removing it if no error occured.
void MarkUpdated( int changeid, string changestatus, string errormessage )
Mark a set of change-rows as handled, removing it if no error occured.
void MarkUpdatedBulk( int[] changeids, string[] changestatuses, string[] errormessages )
Removes all change-rows for a zone and nameserver except the one with a specific id.
Removes all change-rows for an array of zones and nameserver except the ones with specific ids.
Get a list of all zones in the database.
Mark all zones in the database as changed.
Fetch information regarding if updates are disabled or not.
Set or reset the updates disabled flag.
Get the nameserver group for a zone.
Set the nameserver group for a zone.
Add a nameserver group.
Removes an empty nameserver group.
Adds a new slave zone.
void AddSlaveZone( string zonename, string master_ip, string nameservergroup, string tsig_keyname, string tsig_secret )
Removes a slave zone.
Fetches a list of all changed slave zones for a nameserver.
[changes|changes Datatype - Atomia DNS API] GetChangedSlaveZones( string nameserver )
Mark a slave zone change-row as handled, removing it if no error occured.
void MarkSlaveZoneUpdated( int changeid, string changestatus, string errormessage )
Fetches information about a slave zone.
[slavezones|slavezones Datatype - Atomia DNS API] GetSlaveZone( string zonename )
Mark all slave zones in the database as changed.
Get a list of all DNSSEC keys stored in this Atomia DNS instance.
Get a list of generated DS records for all active KSKs stored in this Atomia DNS instance.
[ds_set|ds_set Datatype - Atomia DNS API] GetDNSSECKeysDS( string zone )
Get a list of all external DNSSEC keys stored in this Atomia DNS instance.
Adds a DNSSEC key to the database.
int AddDNSSECKey( string algorithm, int keysize, string keytype, int activated )
Adds an external DNSSEC key to the database.
Marks a DNSSEC key as activated.
Marks a DNSSEC key as deactivated.
Removes a DNSSEC key from the database.
Removes an external DNSSEC key from the database.
Fetch the needed information about all stored ZSKs to be able to perform automated ZSK rollover.
Adds an account with a specified username and password.
Changes the password for an account with a specified username.
Deletes an account.
Get a list of all nameserver groups.
Search for zones in an account.
[findresponse|findresponse Datatype - Atomia DNS API] FindZones( string email, string pattern, int count, int offset )
Do nothing. Meant for generating token without doing anything when authenticating.
#!/usr/bin/perl -w
use strict;
use warnings;
use SOAP::Lite;
use Data::Dumper;
my $soap = SOAP::Lite
-> uri('urn:Atomia::DNS::Server')
-> proxy('http://your.soap.server/atomiadns')
-> on_fault(sub {
my($soap, $res) = @_;
die "got fault of type " . $res->faultcode . ": " .
(ref $res ? $res->faultstring : $soap->transport->status) . "\n";
});
my $res;
$res = $soap->AddZone('example.se', 3600, 'ns1.somecompany.se.', 'registry.somecompany.se.', 10800,
3600, 604800, 86400, [ 'ns1.somecompany.se', 'ns2.somecompany.se' ], 'nameservergroup');
print "AddZone returned " . Dumper($res);
$res = $soap->AddDnsRecords('example.se', [
SOAP::Data->new(name => 'resourcerecord', value => {
label => '@', class => 'IN', ttl => 3600, type => 'A', rdata => '127.0.0.1'
}),
SOAP::Data->new(name => 'resourcerecord', value => {
label => '@', class => 'IN', ttl => 3600, type => 'AAAA', rdata => '2001:0DB8::1'
}),
SOAP::Data->new(name => 'resourcerecord', value => {
label => 'mail', class => 'IN', ttl => 3600, type => 'AAAA', rdata => '2001:0DB8::2'
}),
SOAP::Data->new(name => 'resourcerecord', value => {
label => '@', class => 'IN', ttl => 3600, type => 'MX', rdata => 'mail.example.se.'
})
]);
print "AddDnsRecords returned " . Dumper($res);
Steps:
Create a new command-line application, call it AtomiaDNSExampleClient
Add the WSDL found on http://your.soap.server.installation/wsdl-atomiadns.wsdl as a Web Service Reference called AtomiaDNS
Replace the code with the code below:
using System;
using System.Collections.Generic;
using System.Text;
using AtomiaDNSExampleClient.AtomiaDNS;
namespace AtomiaDNSExampleClient
{
class Program
{
static void Main(string[] args)
{
AtomiaDNSService ws = new AtomiaDNSService();
ws.Url = "http://your.soap.server.installation/atomiadns";
try
{
DeleteZone zone = new DeleteZone();
zone.zonename = "testzone-fromdotnet.com";
DeleteZoneResponse response = ws.DeleteZone(zone);
Console.WriteLine("Zone deleted, got status " + response.status);
}
catch (Exception e)
{
Console.WriteLine("Caught exception when removing zone: " + e);
}
try
{
AddZone zone = new AddZone();
zone.mname = "ns1.atomiadns.com.";
zone.refresh = 10800;
zone.retry = 3600;
zone.expire = 604800;
zone.minimum = 3600;
zone.zonettl = 60;
zone.zonename = "testzone-fromdotnet.com";
zone.rname = "registry.atomiadns.com.";
zone.nameservers = new string[] { "ns1.atomiadns.com.", "ns2.atomiadns.com." };
zone.nameservergroup = "someservergroup";
AddZoneResponse response = ws.AddZone(zone);
Console.WriteLine("Zone added, got status " + response.status);
}
catch (Exception e)
{
Console.WriteLine("Caught exception when adding zone: " + e);
}
}
}
}
Thanks to Alejandro Alvarez for providing us with this Java example.
Steps:
Use wsimport on the WSDL found at http://your.soap.server.installation/wsdl-atomiadns.wsdl to generate SOAP proxy classes.
Contact the API like in the example below:
AtomiaDNSPortType portType = new AtomiaDNSService().getAtomiaDNSPort();
Map<String, Object> req_ctx = ((BindingProvider)portType).getRequestContext();
Map<String, List<String>> headers = new HashMap<String, List<String>>();
headers.put("X-Auth-Username", Collections.singletonList(sysParams.getAtomiaSOAPUsername()));
headers.put("X-Auth-Password", Collections.singletonList(sysParams.getAtomiaSOAPPassword()));
req_ctx.put(MessageContext.HTTP_REQUEST_HEADERS, headers);
GetAllZonesResponse allZonesResponse = portType.getAllZones(null);
Gson gson = new Gson();
String jsonStr = gson.toJson(allZonesResponse.getZones().getZone());