Development of CustomDNS control panel relies on your support! Donations are the sole revenue of the CustomDNS, a service based on JPowerAmin. Please use the PayPal button at the bottom of the page to make a donation. Your contribution goes directly to cover the operating costs of the service and the advancement of the open source control panel.

CustomDNS REST API

Overview

CustomDNS provides RESTful web-services API allowing for full control over zones managed by it. By using the API one can integrate all functionality of CustomDNS 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 the web services must include the account's API key.

The API key for the account get be accessed by signing in, going to “Account Settings”

Account Settings
Figure 1: API Key

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

API Client

An experimental Java based API client is available for download on GitLab. See Cutom-DNS-Client for more info.

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 Properties

Viewing User properties

URL https://www.customdns.ca/jpower-admin/rest/user
Method GET
Accept application/xml or application/json
Return Status Code 200 on success. 4xx or 5xx on Error
Content Type application/xml or application/json

The response type can be controlled by the Accept request header. In the absence of Accept header, the default is XML. For brevity only the XML responses are shown.

Typical response (formatted for readability)

<?xml version="1.0" encoding="UTF-8"?> <user> <dateCreated>2017-12-20T15:26:17-06:00</dateCreated> <dateModified>2019-03-05T08:52:25-06:00</dateModified> <userName>jsabev</userName> <firstName>Jivko</firstName> <lastName>Sabev</lastName> <password>iPlOq6NFpA3rOYn0deLCNALKUJc6pmz8nPDBGx6l5k4=</password> <email>jsabev@nicmus.com</email> <timeZoneId>America/Regina</timeZoneId> <localeName>en-SG</localeName> <apikey>dbda7056-9629-4260-af78-43157d858fb4</apikey> </user>

The user returned correspond to the caller's API key.

Specific User

Users having ROOT privilege can view any user in CustomDNS.

URL https://www.customdns.ca/jpower-admin/rest/user/{userName}
Method GET
Accept application/xml or application/json
Return Status Code 200 on success. 4xx or 5xx on Error
Content Type application/xml or application/json

Updating User properties

URL https://www.customdns.ca/jpower-admin/rest/user
Method PUT
Request Body XML or JSON object representing user to update
Return Status Code 204 on success. 4xx or 5xx on Error

The following user properties can be updated:

  • First Name
  • Last Name
  • Email
  • Password
  • localeName
  • timeZoneId

To change the user password, specify the new password in plain text. The password would be hashed by CustomDNS.

Root users can update any user in CustomDNS. Non-ROOT users an only update their own account.

Example request body to change the password of user jsmith to "jsmit"

<user>
	<userName>jsmith</userName>
	<password>jsmith</password>
</user>

Creating new Users

Root accounts can create new users.

Updating User properties

URL https://www.customdns.ca/jpower-admin/rest/user
Method POST
Request Body XML or JSON object representing user to update
Return Status Code 204 on success. 4xx or 5xx on Error

The following properties are required when creating a user:

  • username
  • password

Example XML request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
	<userName>janedoe</userName>
	<firstName>Jane</firstName>
	<lastName>Doe</lastName>
	<password>password</password>
</user>

Deleting Users

URL https://www.customdns.ca/jpower-admin/rest/user/{userName}
Method DELETE
Return Status Code 204 on success. 4xx or 5xx on Error

Root users can delete any user in CustomDNS. Non Root users can only delete their own account.

Zones

Getting the Zone Count

URL https://www.customdns.ca/jpower-admin/rest/zone/count
Method GET
Return Status Code 200 on success. 5xx on Error
Content Type plain/text - number of zones

Getting the Zone count for a specific user

ROOT users can access zone counts for other users.

URL https://www.customdns.ca/jpower-admin/rest/zone/{userName}/count
Method GET
Return Status Code 200 on success. 5xx on Error
Content Type plain/text - number of zones for the given user

Listing Zones

URL https://www.customdns.ca/jpower-admin/rest/zone/list/
Method GET
Parameter offset
Parameter count
Accept application/xml or application/json
Return Status Code 200 on success. 5xx on Error
Content Type application/xml or application/json

The offset and count parameters are used to paginate the results returned. The default values are 0 and 100 respectively.

Typical response (formatted for readability)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
	<domain>
		<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
		<dateModified>2019-03-06T09:57:32-06:00</dateModified>
		<name>example.com</name>
		<lastCheck>0</lastCheck>
		<type>NATIVE</type>
		<zoneId>20</zoneId>
	</domain>
	<domain>
		<dateCreated>2019-03-06T09:57:36-06:00</dateCreated>
		<dateModified>2019-03-06T09:57:36-06:00</dateModified>
		<name>example.ca</name>
		<lastCheck>0</lastCheck>
		<type>NATIVE</type>
		<zoneId>21</zoneId>
	</domain>
	<domain>
		<dateCreated>2019-03-06T09:57:49-06:00</dateCreated>
		<dateModified>2019-03-06T09:57:49-06:00</dateModified>
		<name>пример.бг</name>
		<lastCheck>0</lastCheck>
		<type>NATIVE</type>
		<zoneId>22</zoneId>
	</domain>
</collection>

Zone listing for specific users

ROOT users can list zones for any user

URL https://www.customdns.ca/jpower-admin/rest/zone/{userName}/list/
Method GET
Parameter offset
Parameter count
Accept application/xml or application/json
Return Status Code 200 on success. 5xx on Error
Content Type application/xml or application/json

Creating

URL https://www.customdns.ca/jpower-admin/rest/zone
Method POST
Parameter userName
Request Body XML or JSON object representing zone to add
Return Status Code 204 on success. 5xx on Error

Example request body

<domain>
	<name>example.za</name>
	<type>NATIVE</type>
</domain>

ROOT users can specify the userName parameter to indicate account for zone.

Deleting

URL https://www.customdns.ca/jpower-admin/rest/zone
Method DELETE
Return Status Code 204 on success. 5xx on Error

Zone Records

Record Count

URL https://www.customdns.ca/jpower-admin/rest/zone/{zoneName}/count
Method GET
Return Status Code 200 on success. 5xx on Error
Content Type text/plain - the number of records in the given zone

Listing

URL https://www.customdns.ca/jpower-admin/rest/zone/{zoneName}/records
Method GET
Parameter offset
Parameter count
Accept application/xml or application/json
Return Status Code 200 on success. 5xx on Error
Content Type application/xml or application/json

The offset and count parameters are used to paginate the results returned. The default values are 0 and 100 respectively.

Typical output (formatted for readability)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<collection>
		<record>
			<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
			<dateModified>2019-03-06T09:57:32-06:00</dateModified>
			<name>example.com</name>
			<type>SOA</type>
			<content>ns1.nicmus.com hostmaster@example.com 0 10800 3600 604800 3600</content>
			<ttl>3600</ttl>
			<prio>0</prio>
			<active>true</active>
			<auth>true</auth>
			<id>603</id>
		</record>
		<record>
			<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
			<dateModified>2019-03-06T09:57:32-06:00</dateModified>
			<name>example.com</name>
			<type>NS</type>
			<content>ns1.nicmus.com</content>
			<ttl>3600</ttl>
			<prio>0</prio>
			<active>true</active>
			<auth>true</auth>
			<id>605</id>
		</record>
		<record>
			<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
			<dateModified>2019-03-06T09:57:32-06:00</dateModified>
			<name>example.com</name>
			<type>NS</type>
			<content>ns2.nicmus.com</content>
			<ttl>3600</ttl>
			<prio>0</prio>
			<active>true</active>
			<auth>true</auth>
			<id>606</id>
		</record>
		<record>
			<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
			<dateModified>2019-03-06T09:57:32-06:00</dateModified>
			<name>example.com</name>
			<type>NS</type>
			<content>ns3.nicmus.com</content>
			<ttl>3600</ttl>
			<prio>0</prio>
			<active>true</active>
			<auth>true</auth>
			<id>607</id>
		</record>
	</collection>

Individual Record Details

URL https://www.customdns.ca/jpower-admin/rest/zone/{zoneName}/record/{id}
Method GET
Accept application/xml or application/json
Return Status Code 200 on success. 5xx on Error
Content Type application/xml or application/json

Typical response (formatted for readability)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<record>
		<dateCreated>2019-03-06T09:57:32-06:00</dateCreated>
		<dateModified>2019-03-06T09:57:32-06:00</dateModified>
		<name>example.com</name>
		<type>NS</type>
		<content>ns1.nicmus.com</content>
		<ttl>3600</ttl>
		<prio>0</prio>
		<active>true</active>
		<auth>true</auth>
		<id>605</id>
	</record>

Creating

URL https://www.customdns.ca/jpower-admin/rest/zone/{zoneName}}
Method POST
Request body application/xml or application/json
Return Status Code 200 on success. 5xx on Error
Content Type text/plain - id of record created

To create a new zone record, the following properties must be present in the request body object

  • name
  • content
  • priority
  • type

Example request to create a new zone record

<record>
		<name>example.com</name>
		<type>NS</type>
		<content>ns4.nicmus.com</content>
		<prio>0</prio>
</record>

Deleting

URL https://www.customdns.ca/jpower-admin/rest/zone/{zoneName}/record/{id}
Method DELETE
Return Status Code 204 on success. 5xx on Error