CustomDNS API

Table of Contents

1 Overview
2 The API Key
3 Using the API
4 Account Management
4.0 Account Properties
4.1 Updating Account Properties
5 Zone Management
5.0 Getting the Zone Count
5.1 Listing Zones
5.2 Zone Details
5.3 Editing a Zone
5.4 Creating a Zone
5.5 Deleting a Zone
5.6 Getting the Record Count
5.7 Listing Zone Records
5.8 Record Details
5.9 Updating a Record
5.10 Creating a Record
5.11 Deleting a Record
6 Payment API
6.0 Renewing Zones

Overview

Custom DNS provides RESTful web-services API allowing for full control over zones hosted with us. By using the API one can integrate all functionality of Custom DNS with third party systems.

The API Key

Each account with CustomDNS gets assigned an API key. The API key is used to uniquely identify an account. Any requests to our web services must include the account's API key. Therefore, it is very important to protect the API key against unauthorised disclosure. Anyone with access to your API key can control all aspects of your account. For this reason, any access to our web-services must be over SSL.

The API key for your account get be accessed by signing in, going to “Account Properties” and viewing the “User Properties” tab

API Key
Figure 1: API Key

The “Generate New” link can be used to generate a new API key.

Using the API

Every request to our web-services URLs must include the custom HTTP header X-customDNS-API-Key set to the API key for the user's account.

Account Management

Account Properties

URL https://www.customdns.ca/seam/resource/restv2/user
Method GET
Returns 200 & application/xml

The web-service returns xml markup representing the user properties.

Typical response (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <user> <firstName>John</firstName> <lastName>Smith</lastName> <userName>jsmith</userName> <password>39ce7e2a8573b41ce73b5ba41617f8f7</password> <email>jsmith@example.com</email> <billingAddress> <firstName>John</firstName> <lastName>Smith</lastName> <streetAddress>123 Anytown</streetAddress> <streetAddress2></streetAddress2> <city>AnyCity</city> <province>Any Province</province> <postalCode>A1A 1A1</postalCode> <country>Canada</country> <email>jsmith@example.com</email> <phoneNumber>+1 123 123 1234</phoneNumber> </billingAddress> <dateCreated>2010-07-29T16:14:05-06:00</dateCreated> <dateModified>2010-07-30T10:56:10-06:00</dateModified> </user>

The billingAddress tag encapsulates the address that would be used when processing credit card transactions. The billing address must match that of the credit card used to renew zones hosted with Custom DNS.

The email tag in the user properties is the email address where reminders pertinent to the account are sent to.

The email tag in the billingAddress is the address where confirmation of billing is sent to.

The password tag shows the one-way hashed password for the account.

Updating Account Properties

To update the account properties, submit the XML representation of the user to the web service URL below.

URL https://www.customdns.ca/seam/resource/restv2/user
Method PUT
Request Body XML (application/xml) representing user to update
Returns
200 OK
400 Bad Request on invalid XML

Typical xml request (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <user> <firstName>John</firstName> <lastName>Smith</lastName> <userName>jsmith</userName> <password>newpassword</password> <email>jsmith@example.net</email> <billingAddress> <firstName>John</firstName> <lastName>Smith</lastName> <streetAddress>123 Anytown</streetAddress> <streetAddress2></streetAddress2> <city>AnyCity</city> <province>Any Province</province> <postalCode>A1A 1A1</postalCode> <country>Canada</country> <email>jsmith@example.com</email> <phoneNumber>+1 123 123 1234</phoneNumber> </billingAddress> </user>

To change the password, put the new password in plain-text in the password tag. The password will be then hashed by the server.

Please note that the user name, date created and date modified properties cannot be changed.

Zone Management

Getting the Zone Count

To find out the number of zones for the current account, use the following URL

URL https://www.customdns.ca/seam/resource/restv2/zones/count
Method GET
Returns
200 OK & text/plain - total number of zones for current account

Listing Zones

To get a listing of all zones for a given account, use the following URL

URL https://www.customdns.ca/seam/resource/restv2/zones
Method GET
Returns
200 OK & application/xml representing all zones

Typical output (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <collection> <domain> <name>example.com</name> <type>MASTER</type> <master></master> <notifiedSerial>0</notifiedSerial> <active>true</active> <deleted>false</deleted> <expired>false</expired> <dateCreated>2010-07-29T16:14:16-06:00</dateCreated> <dateModified>2010-07-29T16:14:41-06:00</dateModified> <expiryDate>2010-08-28T16:14:16-06:00</expiryDate> </domain> <domain> <name>example.bg</name> <type>MASTER</type> <master></master> <notifiedSerial>0</notifiedSerial> <active>true</active> <deleted>false</deleted> <expired>false</expired> <dateCreated>2010-07-29T16:14:21-06:00</dateCreated> <dateModified>2010-07-29T16:14:41-06:00</dateModified> <expiryDate>2010-08-28T16:14:21-06:00</expiryDate> </domain> </collection>

The zone listing is limited to the first one thousand zones for the current account. If the account contains more than one thousand zones, use the following URL parameters to access zones beyond the one thousand limit.

offset: specifies the starting position of the zones

count: specifies the number of records to return

Example: https://www.customdns.ca/seam/resource/restv2/zones?offset=1000&count=500

Zone Details

Zones are uniquely identified by name. One can get the zone details by querying the following URL

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]
Method GET
Returns
200 OK & application/xml representing zone
404 Not Found

Typical output (formatted for readability)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <domain> <name>example.com</name> <type>MASTER</type> <master></master> <notifiedSerial>0</notifiedSerial> <active>true</active> <deleted>false</deleted> <expired>false</expired> <dateCreated>2010-07-29T16:14:16-06:00</dateCreated> <dateModified>2010-07-29T16:14:41-06:00</dateModified> <expiryDate>2010-08-28T16:14:16-06:00</expiryDate> </domain>

The master tag indicates the IP address of the master DNS server in case this is a slave zone as indicated by the type tag.

Editing a Zone

Edits to zones are performed by submitting the XML zone representation to the web services URL.

URL https://www.customdns.ca/seam/resource/restv2/zone
Method PUT
Request body XML (application/xml) markup identifying the zone to edit
Returns
200 OK
400 Bad Request on invalid XML
404 Not Found

Typical request body (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <domain> <name>example.com</name> <type>MASTER</type> <master></master> <notifiedSerial>0</notifiedSerial> <active>false</active> </domain>

The active tag indicates the status of the domain - true for active, false for disabled. To disable domain, set the active tag to false.

Creating a Zone

To create a zone use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone
Method POST
Request body XML (application/xml) markup of a zone
Returns
200 OK
400 Bad Request on invalid XML
409 Conflict

Typical request body (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <domain> <name>example.za</name> <type>MASTER</type> </domain>

Deleting a Zone

To delete a zone use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]
Method DELETE
Returns
200 OK
404 Not Found

Getting the Record Count

To get the number of records for a zone, use the following URL.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]/count
Method GET
Returns
200 OK & text/plain - number of DNS records for given zone

Listing Zone Records

Zone records can be listed by requesting the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]/records
Method GET
Returns
200 OK & XML (application/xml) representation of the zone records
404 Not Found

Typical output (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <collection> <record> <id>64</id> <name>example.com</name> <type>SOA</type> <content>ns1.nicmus.com hostmaster.example.com 1 10800 3600 604800 3600</content> <prio>0</prio> <ttl>3600</ttl> <change_date>1280963926277</change_date> <dateCreated>2010-07-29T16:14:16-06:00</dateCreated> <dateModified>2010-08-04T17:18:46-06:00</dateModified> </record> <record> <id>65</id> <name>example.com</name> <type>NS</type> <content>ns1.nicmus.com</content> <prio>0</prio> <ttl>3600</ttl> <change_date>1280441656529</change_date> <dateCreated>2010-07-29T16:14:16-06:00</dateCreated> <dateModified>2010-07-29T16:14:16-06:00</dateModified> </record> <record> <id>66</id> <name>example.com</name> <type>NS</type> <content>ns2.nicmus.com</content> <prio>0</prio> <ttl>3600</ttl> <change_date>1280441656530</change_date> <dateCreated>2010-07-29T16:14:16-06:00</dateCreated> <dateModified>2010-07-29T16:14:16-06:00</dateModified> </record> <record> <id>80</id> <name>www.example.com</name> <type>A</type> <content>173.203.79.71</content> <prio>0</prio> <ttl>3600</ttl> <change_date>1280963926250</change_date> <dateCreated>2010-08-04T17:18:46-06:00</dateCreated> <dateModified>2010-08-04T17:18:46-06:00</dateModified> </record> </collection>

The name tag identifies the name of the record - that is the content on the left hand side in the DNS database.

The content tag identifies what the record point to - that is the content on the right hand side in the DNS database.

The type tag refers to the DNS record type.

The prio tag refers to the record priority. Mainly useful for MX records.

The ttl is the record Time to Live.

The change_date is the time in milliseconds since the start of the epoch. This value is automatically set every time you update a DNS record.

For a complete list of record types and their storage, consult the powerDNS manual.

Only the first one thousand records are listed. for zones with more records, use the following parameters to access records beyond one thousand.

offset: specifies the starting position of the records

count: specifies the number of records to return

Example: https://www.customdns.ca/seam/resource/restv2/zone/[zonename]/records?offset=1000&count=500

Record Details

Zone records are uniquely identified by ids. To view the details of a particular record, use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zoneName]/record/[id]
Method GET
Returns
200 OK & application/xml
404 Not Found

Typcial output (formatted for readability)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <record> <id>80</id> <name>www.example.com</name> <type>A</type> <content>173.203.79.71</content> <prio>0</prio> <ttl>3600</ttl> <change_date>1280963926250</change_date> <dateCreated>2010-08-04T17:18:46-06:00</dateCreated> <dateModified>2010-08-04T17:18:46-06:00</dateModified> </record>

Updating a Record

To edit a zone record, submit the XML representation of the given record to the following URL.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]
Method PUT
Request body XML (application/xml) identifying zone record to edit
Returns
200 OK
400 Bad Request on invalid XML
404 Not Found
409 Record Conflict

Creating a Record

To create a new record, use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]
Method POST
Request body XML (application/xml) representation of record
Returns
200 OK & text/plain - id of record created
400 Bad Request on invalid XML
404 Not Found
409 Conflict

Typical request body (formatted for readability).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <record> <name>example.com</name> <type>MX</type> <content>mx1.nicmus.com</content> <prio>1</prio> <ttl>3600</ttl> </record>

In the example above, an MX record with priority 1 pointing to mx1.nicmus.com is being created for the zone example.com

Deleting a Record

To delete a zone record, use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/zone/[zonename]/record/[id]
Method DELETE
Returns
200 OK
404 Not Found

Payment API

Through the use of the payment API, one is able to renew the hosting period of zones hosted with CustomDNS. In order to use the payment API, you must have the billing address of the credit card used in the API requests match the billing address of your account. To set up your billing address, login to your account and enter your billing address in the “Account Properties” section of the control panel.

Visa and Matercard credit cards are accepted.

Renewing Zones

To renew the hosting period of zones with CustomDNS, use the following resource.

URL https://www.customdns.ca/seam/resource/restv2/renew
Method POST
Request body XML (application/xml)
Returns
200 OK & XML (application/xml) of response
400 Bad Request
404 Not Found

A typical request to the renewal URL looks as follows.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <renewRequest> <creditCardDetails> <number>4012888888881881</number> <expiryMonth>02</expiryMonth> <expiryYear>12</expiryYear> <securityCode>123</securityCode> </creditCardDetails> <requests> <domain>example.com</domain> <years>1</years> </requests> <requests> <domain>example.bg</domain> <years>2</years> </requests> </renewRequest>

The creditCardDetails tag encapsulates all credit card details required to make a payment.

The expiryYear tag is the two digit year corresponding to the expiration date of the credit card — 10 for 2010, 11 for 2011, etc.

The securityCode specifies the CVV code of the credit card used to make the payment.

In accordance with our privacy policy, no credit card details are kept on our servers. Credit card details include the credit card number, the expiry date and the CVV code.

A typical response of a payment request follows.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <orderResult> <orderId>2010080911185105661</orderId> <orderStatus>APPROVED</orderStatus> <returnCode>Y:123456:0abcdef:M:X:NNN</returnCode> </orderResult>