REST API v1.1 - Managed DNS

Managed DNS - REST API v1.1

Introduction and Overview

Zerigo DNS supports a fairly standard REST API for full creation, modification, and deletion of domain (zone) and host records. It is easy and straightforward to work with.

Note that in the context of the API, domains are always referred to as zones. Zones (domains), hosts, zone templates (templates), and host templates (hosts for zone templates) are all supported.

API status

This is the current version of the API. All new development should use this version. Additionally, users of an older version of the API should plan to upgrade to the latest version. See the documentation for the older versions for sunset dates.

REST API Basics

REST runs on top of HTTP. It uses standard GET, POST, PUT, and DELETE methods for HTTP along with XML document bodies. Authentication is sent as an HTTP basic auth header.

Authentication

Authentication for all API requests is done via a standard Basic HTTP Auth header. The username is your email address and the password is the dynamic update token available in Manage Account → DNS → Preferences. You must enable dynamic updates to use the API.

Content types

A Content-Type header is required for all POST or PUT requests. If your content is sent as XML (recommended), you must send Content-Type: application/xml. All examples within our documentation are XML and must use the application/xml mime-type. A Content-Type header should not be sent with GET or DELETE requests.

You may also send standard web-form content with the application/x-www-form-urlencoded mime-type. Parameters should be translated like this: <zone><domain>example.com</domain><ns-type>pri_sec</ns-type></zone> becomes zone[domain]=example.com&zone[ns_type]=pri_sec. Note that ns-type became ns_type. The rule is this: use hyphens for XML node names and use underscores for web-form content or URL query parameters.

If your HTTP client cannot send PUT and DELETE verbs, you may substitute the parameter _method=put along with a POST request. This only works for web-form content and the _method parameter must be in the POST body, not in the query string. It is recommended that you use an HTTP client capable of using PUT and DELETE verbs.

HTTP Request Specifics

The URL endpoint for this API is http://ns.zerigo.com/api/1.1/. https is
supported.

The HTTP status code in the response is an important part of the API. Where possible we attempt to indicate results by way of the status code. At times the status code is sufficient to communicate the entire response and the body of the response will be blank.

Common response codes are:

200 – OK
201 – Created
401 – Credentials required
403 – Forbidden (Credentials understood but not acceptable for this request)
404 – Not found (The requested object was not found)
405 – Method not allowed (Probably a mixup between GET, POST, PUT, and DELETE)
415 – Unsupported media type (Check that the Content-Type header is correct)
422 – Field validation error
426 – Upgrade required (Check current service plan usage/limits)
500 – Server error
503 – Service temporarily unavailable

Validation errors (status 422)

A 422 response code indicates an error with the data submitted (via a POST or PUT call). Text details about the errors are provided in the response body.

<errors>
  <error>The name field is required.</error>
</errors>
Service unavailable (status 503)

A 503 response code is returned for two different, but related reasons.

1. Our API servers are overloaded.
2. Rate-limit quotas for your IP or account have been reached.

It is recommended that you wait a short while before retrying the request.

Zones - Overview and Fields

Zones are called Domains in our web interface.

Fields

axfr-ips
A comma-separated list of IPs or IP blocks allowed to perform AXFRs for this domain. Only valid for master/primary domains and if restrict-axfr is enabled. (optional; read/write)
created-at
Initial creation time of this resource. (readonly)
custom-nameservers
A comma-separated list of custom nameservers. If nil, the domain will use Zerigo’s default list of servers. Only valid for domains with custom-ns enabled. (optional; read/write)
custom-ns
Indicates if vanity (custom) nameservers are enabled for this domain. Only allowed if the account’s service plan supports vanity nameservers. (optional; read/write)
default-ttl
Default TTL (time-to-live), in seconds, for host records attached to this zone. (required; read/write)
domain
The domain name (required; read/write)
follow-template
One of ‘no’ or ‘follow’. When ‘follow’, will inherit changes from the associated Zone Template. When ‘no’ and a zone_template_id is present, will copy once from that Zone Template (and then clear zone_template_id). (optional; read/write)
hostmaster
The email of the DNS administrator or hostmaster. A nil value will default to Zerigo’s hostmaster address. Note that this is publicly visible in the domain records. Only valid for domains with custom-ns enabled. (optional; read/write)
hosts
An array of host records. See Hosts. (readonly)
hosts-count
Total number of hosts that belong to this zone. (readonly)
id
Unique ID for this zone. (readonly)
notes
Notes about the domain. (optional; read/write)
ns1
The remote master nameserver, required when ns-type is ‘sec’. (read/write)
ns-type

Three valid values: ‘pri_sec’, ‘pri’, and ‘sec’ which are: Standard service (normal), Standard service with Master support, and Slave only service respectively.

The value of ns-type will determine whether ns1 or slave-nameservers are used. If ns-type is ‘pri’, then slave-nameservers should be used to provide a comma-separated list of slave nameservers (eg: “ns1.some-slave.com,ns2.some-slave.com”). If ns-type is ‘sec’, then ns1 is used to designate the master nameserver. Both ns1 and slave-nameservers should be left blank when using the ‘pri-sec’ service.

ns2 and ns3
(along with ns1, which had dual-use) used to hold the slave nameservers for ‘pri’ service. ns2 and ns3 are now fully deprecated and should no longer be used or even included in any POST OR PUT requests. They will be removed in the next version of the API. For backwards compatibility in this version, when ns-type is ‘pri’, ns1, ns2, and ns3 will contain the first 3 values from slave-nameservers.
nx-ttl
Default “domain/host not found” TTL (time-to-live), in seconds, when a host record for this domain doesn’t exist. If nil, our nameservers will use the lesser of 3 hours or the default-ttl value. (optional; read/write)
restrict-axfr
Indicates if AXFR transfers should be restricted to the list of IPs in axfr-ips. Only valid for master/primary domains. (optional; read/write)
slave-nameservers
The remote slave nameservers, in a comma-separated list. Required when ns-type is ‘pri’. (read/write)
tag-list
List of all tags associated with this domain. Tags are space separated; use quotes for multi-word tags. (optional; read/write)
updated-at
Last update time of this resource. (readonly)
zone-template-id
The ID of the Zone Template to inherit or copy from. See follow_template above. (read/write)

Zones - List all zones

Request

Example
GET /api/1.1/zones.xml

GET /api/1.1/zones.xml?per_page=25&page=2
Notes

There are two optional parameters: page=# and per_page=#. page defaults to 1 (and starts at 1, not 0). per_page defaults to 100 but should be specified exactly if a change of the default value will cause your application to fail. The maximum value for per_page is 1000.

Response

Example header
X-Query-Count: 12
Example body
<zones type="array">
  <zone>
    <created-at type="datetime">2008-12-07T02:40:02Z</created-at>
    <custom-nameservers nil="true"/>
    <custom-ns type="boolean">false</custom-ns> 
    <default-ttl type="integer">600</default-ttl>
    <domain>example.com</domain>
    <hostmaster nil="true"/> 
    <id type="integer">12345678</id>
    <notes nil="true"/>
    <ns1 nil="true"/>
    <ns-type>pri_sec</ns-type>
    <nx-ttl nil="true"/> 
    <slave-nameservers nil="true"/>
    <updated-at type="datetime">2008-12-07T02:40:02Z</updated-at>
  </zone>
</zones>
Notes

X-Query-Count will contain the total number of results, including those that didn’t fit inside this response. For example, if there are 12 results and per_page (above) is 10, only 10 entries will be returned but X-Query-Count will show 12 so that you know there are more results remaining.

Zones - Count all zones

This is the total number of zones available. It is the same value as provided in the X-Query-Count header in the Managed DNS → List all zones API method.

Request

Example
GET /api/1.1/zones/count.xml

Response

Example body
<count>12</count>

Zones - Get a zone

This response is similar to Listing All Zones, with the addition of hosts-count and possibly hosts. As long as there are no more than 300 hosts, they will be returned. If there are more, the hosts array will be left out. hosts-count will always be returned.

Request

Example
GET /api/1.1/zones/12345678.xml

GET /api/1.1/zones/example.com.xml (to retrieve the record for example.com)

Response

Example body
<zone>
  <created-at type="datetime">2008-12-07T02:40:02Z</created-at>
  <custom-nameservers>ns1.example.com,ns2.example.com</custom-nameservers>
  <custom-ns type="boolean">true</custom-ns> 
  <default-ttl type="integer">600</default-ttl>
  <domain>example.com</domain>
  <hostmaster>dnsadmin@example.com</hostmaster> 
  <id type="integer">12345678</id>
  <notes nil="true"/>
  <ns1 nil="true"/>
  <ns-type>pri_sec</ns-type>
  <nx-ttl nil="true"></nx-ttl>
  <slave-nameservers nil="true"/>
  <tag-list>one two</tag-list>
  <updated-at type="datetime">2008-12-07T02:40:02Z</updated-at>
  <hosts-count>1</hosts-count>
  <hosts type="array">
    <host>
      <created-at type="datetime">2008-12-07T02:51:13Z</created-at>
      <data>172.16.16.1</data>
      <fqdn>example.com</fqdn>
      <host-type>A</host-type>
      <hostname nil="true"/>
      <id type="integer">23456789</id>
      <notes nil="true"/>
      <priority type="integer" nil="true"/>
      <ttl type="integer" nil="true"/>
      <updated-at type="datetime">2008-12-07T02:51:13Z</updated-at>
      <zone-id type="integer">12345678</zone-id>
    </host>
  </hosts>
</zone>

Zones - Get stats for a zone

This response returns current traffic statistics about this zone. Queries is measured from the beginning of the current period through the time of the API call. Just like everywhere else in our system, dates are based on UTC.

This API may be rate limited differently than other APIs.

Request

Example
GET /api/1.1/zones/12345678/stats.xml

Response

Example body
<zone>
  <domain>example.com</domain>
  <id type="integer">12345678</id>
  <period-begin type="date">2010-07-01</period-begin>
  <period-end type="date">2010-07-31</period-end>
  <queries type="integer">1357</queries>
</zone>

Zones - Get a blank zone

This response may be useful to obtain a blank zone, suitable for use as a template or retrieving default values for included fields.

Request

Example
GET /api/1.1/zones/new.xml

Response

Example body
<zone>
  <custom-ns type="boolean">false</custom-ns>
  <default-ttl type="integer">600</default-ttl>
  <domain nil="true"/>
  <ns1 nil="true"/>
  <ns-type>pri_sec</ns-type>
  <nx-ttl nil="true"/> 
  <slave-nameservers nil="true"/>
</zone>

Zones - Create a zone

Request

Example
POST /api/1.1/zones.xml

<zone>
  <default-ttl type="integer">600</default-ttl>
  <domain>example.com</domain>
  <ns1 nil="true"/>
  <ns-type>pri_sec</ns-type>
  <nx-ttl type="integer">900</nx-ttl> 
  <slave-nameservers nil="true"/>
</zone>
Notes

ns1 should be left out unless ns-type is ‘sec’. slave-nameservers should be left out unless ns-type is ‘pri’. See more details under Zones Overview.

Response

Example header
Location: http://ns.zerigo.com/api/1.1/zones/12345679.xml
Example body
<zone>
  <created-at type="datetime">2008-12-07T02:40:02Z</created-at>
  <custom-nameservers>ns1.example.com,ns2.example.com</custom-nameservers>
  <custom-ns type="boolean">true</custom-ns> 
  <default-ttl type="integer">600</default-ttl>
  <domain>another-example.com</domain>
  <hostmaster>dnsadmin@example.com</hostmaster> 
  <id type="integer">12345679</id>
  <notes nil="true"/>
  <ns1 nil="true"/>
  <ns-type>pri_sec</ns-type>
  <nx-ttl nil="true"></nx-ttl>
  <slave-nameservers nil="true"/>
  <tag-list nil="true"/>
  <updated-at type="datetime">2008-12-07T02:40:02Z</updated-at>
  <hosts-count>0</hosts-count>
  <hosts type="array"/>
</zone>
Notes

Status 201 on success.
Status 422 on validation error.

Zones - Update a zone

Request

Example
PUT /api/1.1/zones/12345678.xml

<zone>
  <default-ttl type="integer">600</default-ttl>
  <notes>Random notes</notes>
  <ns1 nil="true"/>
  <ns-type>pri_sec</ns-type>
  <slave-nameservers nil="true"/>
  <tag-list>one two</tag-list>
</zone>
Notes

ns1 should be left out unless ns-type is ‘sec’. slave-nameservers should be left out unless ns-type is ‘pri’. See more details under Zones Overview.

Response

Notes

Status 200 on success.
Status 422 on validation error.

Zones - Delete a zone

Request

Example
DELETE /api/1.1/zones/12345678.xml

Response

Notes

Status 200 on success.

Hosts - Overview and Fields

Fields

created-at
Initial creation time of this resource. (readonly)
data
The required format of data depends on host-type; see below. (required; read/write)
fqdn
Fully qualified domain name (hostname + domain). (readonly)
host-type
DNS host record type; see below. (required; read/write)
hostname
Any part of a domain in front of the domain itself (aka a subdomain). For example, for a fully qualified domain name of ‘www.example.com’, where the zone domain is ‘example.com’, the hostname would be ‘www’. If there isn’t any hostname in front of the domain name, this should be set as nil or left out. Wildcard hostnames are supported (eg: ‘*’ or ‘*.subdomain’). (optional; read/write)
id
Unique ID for this host. (readonly)
notes
Notes about the host. (optional; read/write)
priority
Indicates the relative priority of two or more of certain host-types, such as MX or SRV. For example, this may be set to 10 for a primary mail server and 20 for a backup server.
ttl
TTL (time-to-live), in seconds. If nil, the record uses the default-ttl value from the zone. (optional; read/write)
updated-at
Last update time of this resource. (readonly)
zone-id
ID of the zone to which this record is attached. (readonly)
Host-type and Data

Zerigo supports a number of different host-types. Valid values are A, AAAA, CNAME, GEO, MX, NS, SPF, SRV, TXT, and URL. For reverse domains, the only valid values are PTR, CNAME, and NS.

host-type should be ‘A’ to set an Address record. This points a full hostname (www.example.com) to a specific IPv4 address (172.16.16.1) which should be in the data field.

host-type should be ‘AAAA’ to set an IPv6 Address record.

host-type should be ‘MX’ to set a Mail eXchange record. This indicates where email for a full hostname (www.example.com) should be delivered — by using a hostname in the data field (mail.example.com). Also see the priority field.

host-type should be ‘CNAME’ to create a Canonical Name record. This points one hostname as an alias to another which should be entered as a hostname in the data field (othername.example.com). The CNAME hostname in the data field should not point to another CNAME record. DNS specifications prohibit having a CNAME on the base domain. Wildcard CNAMEs aren’t blocked, but in certain circumstances can exhibit unexpected behavior; contact support to discuss your use-case.

Use a host-type of ‘GEO’ for GeoDNS records. This would be the root/base domain of a GeoDNS configuration. Additional records will be other various record types. The data field of a GEO record can be left out as it will be automatically managed.

A host-type of ‘NS’ is used to delegate DNS for subdomains. Non-subdomain NS records cannot be set this way. The data field for NS records should be a fully qualified domain name of the target nameserver.

host-type should be ‘PTR’ when the zone is a reverse domain. Reverse domains for both IPv4 and IPv6 are supported and are auto-detected based on the zone’s domain name. The data field for PTR records should be a fully qualified domain name.

A host-type of ‘SRV’ will configure a SeRVice record. The data field should contain the weight, port number, and full domain name, for example: 10 389 ldap.example.com. The priority field is also required.

host-type should be ‘TXT’ to configure a text record. The text itself should be entered in the data field. A common use of this is setting an SPF record for a domain, but see the next paragraph.

Also supported is a host-type of ‘SPF’. Records with SPF content can be entered using either an SPF or TXT record type according to the SPF specifications. SPF is now preferred, but TXT was originally used. Zerigo supports both. For maximum compatibility with email servers across the globe, you may want to consider using both.

Redirects use the special host-type ‘URL’. The data field should be a valid URI.

Hosts - List hosts

This API method has two uses:

  • Listing hosts that belong to a specific zone
  • Searching for hosts the belong to any zone or a specific zone

Request

Example
GET /api/1.1/zones/12345678/hosts.xml

GET /api/1.1/zones/12345678/hosts.xml?per_page=10&page=2

GET /api/1.1/hosts.xml?zone_id=12345678

GET /api/1.1/zones/12345678/hosts.xml?fqdn=www.example.com

GET /api/1.1/hosts.xml?fqdn=www.example.com
Notes

There are two optional parameters: page=# and per_page=#. page defaults to 1 (and starts at 1, not 0). per_page defaults to 100 but should be specified exactly if a change of the default value will cause your application to fail. The maximum value for per_page is 1000.

It is possible to search by hostname to limit the result set. Searches are based on the FQDN (fully qualified domain name) which is the combination of the hostname (if any) and the zone/domain name.

If the FQDN matches the zone’s domain exactly, then the search will be for records with a hostname of nil.

Response

Example header
X-Query-Count: 12
Example body
<hosts type="array">
  <host>
    <created-at type="datetime">2008-12-07T02:51:13Z</created-at>
    <data>172.16.16.1</data>
    <fqdn>example.com</fqdn>
    <host-type>A</host-type>
    <hostname nil="true"/>
    <id type="integer">23456789</id>
    <notes nil="true"/>
    <priority type="integer" nil="true"/>
    <ttl type="integer" nil="true"/>
    <updated-at type="datetime">2008-12-07T02:51:13Z</updated-at>
    <zone-id type="integer">12345678</zone-id>
  </host>
</hosts>
Notes

X-Query-Count will contain the total number of results, including those that didn’t fit inside this response. For example, if there are 12 results and per_page (above) is 10, only 10 entries will be returned but X-Query-Count will show 12 so that you know there are more results remaining.

Hosts - Count all hosts

This is the total number of hosts available for the specified zone. It is the same result as provided in the X-Query-Count header in the Managed DNS → List hosts API method.

Request

Example
GET /api/1.1/zones/12345678/hosts/count.xml

GET /api/1.1/hosts/count.xml?zone_id=12345678

Response

Example body
<count>12</count>

Hosts - Get a host

Request

Example
GET /api/1.1/hosts/12345678.xml

Response

Example body
<host>
  <created-at type="datetime">2008-12-07T02:51:13Z</created-at>
  <data>172.16.16.1</data>
  <fqdn>example.com</fqdn>
  <host-type>A</host-type>
  <hostname nil="true"/>
  <id type="integer">23456789</id>
  <notes nil="true"/>
  <priority type="integer" nil="true"/>
  <ttl type="integer" nil="true"/>
  <updated-at type="datetime">2008-12-07T02:51:13Z</updated-at>
  <zone-id type="integer">12345678</zone-id>
</host>

Hosts - Get a blank host

This response may be useful to obtain a blank host, suitable for use as a template or retrieving default values for included fields. zone_id will be populated only if provided.

Request

Example
GET /api/1.1/hosts/new.xml

GET /api/1.1/zones/12345678/hosts/new.xml

GET /api/1.1/hosts/new.xml?zone_id=12345678

Response

Example body
<host>
  <data nil="true"/>
  <host-type>A</host-type>
  <hostname nil="true"/>
  <priority type="integer" nil="true"/>
  <ttl type="integer" nil="true"/>
</host>

Hosts - Create a host

Request

Example
POST /api/1.1/zones/12345678/hosts.xml

POST /api/1.1/hosts.xml?zone_id=12345678

<host>
  <data>172.16.16.2</data>
  <host-type>A</host-type>
  <hostname>www</hostname>
  <priority type="integer" nil="true"/>
  <ttl type="integer" nil="true"/>
</host>
Notes

hostname, priority, and ttl may be left out entirely if their value is nil.

Response

Example header
Location: http://ns.zerigo.com/api/1.1/hosts/23456780.xml
Example body
<host>
  <created-at type="datetime">2008-12-07T02:51:13Z</created-at>
  <data>172.16.16.1</data>
  <fqdn>example.com</fqdn>
  <host-type>A</host-type>
  <hostname nil="true"/>
  <id type="integer">23456780</id>
  <notes nil="true"/>
  <priority type="integer" nil="true"/>
  <ttl type="integer" nil="true"/>
  <updated-at type="datetime">2008-12-07T02:51:13Z</updated-at>
  <zone-id type="integer">12345678</zone-id>
</host>
Notes

Status 201 on success.
Status 422 on validation error.

Hosts - Update a host

Request

Example
PUT /api/1.1/hosts/23456789.xml

<host>
  <data>172.16.16.2</data>
  <host-type>A</host-type>
  <hostname>www</hostname>
  <priority type="integer" nil="true"/>
  <ttl type="integer" nil="true"/>
</host>

Response

Notes

Status 200 on success.
Status 422 on validation error.

Hosts - Delete a host

Request

Example
DELETE /api/1.1/hosts/23456789.xml

Response

Notes

Status 200 on success.

Zone templates - Overview and Fields

Fields

axfr-ips
A comma-separated list of IPs or IP blocks allowed to perform AXFRs for this template’s domains. Only valid for master/primary templates and if restrict-axfr is enabled. (optional; read/write)
created-at
Initial creation time of this resource. (readonly)
custom-nameservers
A comma-separated list of custom nameservers. If nil, the template will use Zerigo’s default list of servers. Only valid for templates with custom-ns enabled. (optional; read/write)
custom-ns
Indicates if custom (vanity) nameservers are enabled for this template. Only allowed if the account’s service plan supports custom nameservers. (optional; read/write)
default-ttl
Default TTL (time-to-live), in seconds, for host records attached to this zone template. (required; read/write)
hostmaster
The email of the DNS administrator or hostmaster. A nil value will default to Zerigo’s hostmaster address. Note that this is publicly visible in the domain records. Only valid for templates with custom-ns enabled. (optional; read/write)
host-templates
An array of host records. See Host Templates. (readonly)
host-templates-count
Total number of hosts that belong to this template. (readonly)
id
Unique ID for this zone template. (readonly)
name
A name for this template. (required; read/write)
notes
Notes about the template. (optional; read/write)
ns1
The remote master nameserver, required when ns-type is ‘sec’. (read/write)
ns-type
One of ‘pri_sec’, ‘pri’, and ‘sec’. See Zones Overview for details. (required; read/write)
nx-ttl
Default “domain/host not found” TTL (time-to-live), in seconds, when a host record for this template doesn’t exist. If nil, our nameservers will use the lesser of 3 hours or the default-ttl value. (optional; read/write)
restrict-axfr
Indicates if AXFR transfers should be restricted to the list of IPs in axfr-ips. Only valid for master/primary templates. (optional; read/write)
slave-nameservers
The remote slave nameservers, in a comma-separated list. Required when ns-type is ‘pri’. (read/write)
updated-at
Last update time of this resource. (readonly)

Zone templates - List all templates

Request

Example
GET /api/1.1/zone_templates.xml

GET /api/1.1/zone_templates.xml?per_page=100&page=1
Notes

There are two optional parameters: page=# and per_page=#. page defaults to 1 (and starts at 1, not 0). per_page defaults to 100 but should be specified exactly if a change of the default value will cause your application to fail. The maximum value for per_page is 1000.

Response

Example header
X-Query-Count: 12
Example body
<zone-templates type="array">
  <zone-template>
    <created-at type="datetime">2010-01-26T07:43:14Z</created-at>
    <custom-nameservers></custom-nameservers>
    <custom-ns type="boolean">false</custom-ns>
    <default-ttl type="integer">900</default-ttl>
    <hostmaster nil="true"></hostmaster>
    <id type="integer">12345678</id>
    <name>Some Template</name>
    <notes>notes about the template</notes>
    <ns-type>pri_sec</ns-type>
    <nx-ttl nil="true"/>
    <ns1 nil="true"/>
    <slave-nameservers/>
    <updated-at type="datetime">2010-01-26T07:51:26Z</updated-at>
  </zone-template>
</zone-templates>
Notes

X-Query-Count will contain the total number of results, including those that didn’t fit inside this response. For example, if there are 12 results and per_page is 10, only 10 entries will be returned but X-Query-Count will show 12 so that you know there are more results remaining.

Zone templates - Count all templates

This is the total number of zone templates available. It is the same value as provided in the X-Query-Count header in the Managed DNS → List all templates API method.

Request

Example
GET /api/1.1/zone_templates/count.xml

Response

Example body
<count>12</count>

Zone templates - Get a template

This response is similar to List all templates with the addition of host-templates-count and possibly host-templates. As long as there are no more than 300 host templates, they will be returned. If there are more, the host-templates array will be left out. host-templates-count will always be returned.

Request

Example
GET /api/1.1/zone_templates/12345678.xml

Response

Example body
<zone-template>
  <created-at type="datetime">2010-01-26T07:43:14Z</created-at>
  <custom-nameservers></custom-nameservers>
  <custom-ns type="boolean">false</custom-ns>
  <default-ttl type="integer">900</default-ttl>
  <host-templates type="array">
    <host-template>
      <created-at type="datetime">2010-01-27T07:37:05Z</created-at>
      <data>10.10.10.10</data>
      <host-type>A</host-type>
      <hostname>www</hostname>
      <id type="integer">23456789</id>
      <notes nil="true"/>
      <priority nil="true"></priority>
      <ttl nil="true"></ttl>
      <updated-at type="datetime">2010-01-27T07:37:05Z</updated-at>
      <zone-template-id type="integer">12345678</zone-template-id>
    </host-template>
  </host-templates>
  <host-templates-count type="integer">1</host-templates-count>
  <hostmaster nil="true"></hostmaster>
  <id type="integer">12345678</id>
  <name>Some Template</name>
  <notes>notes about the template</notes>
  <ns-type>pri_sec</ns-type>
  <ns1 nil="true"></ns1>
  <nx-ttl nil="true"></nx-ttl>
  <slave-nameservers></slave-nameservers>
  <updated-at type="datetime">2010-01-26T07:51:26Z</updated-at>
</zone-template>

Zone templates - Get a blank template

This response may be useful to obtain a blank template, suitable for use as a guide or retrieving default values for included fields.

Request

Example
GET /api/1.1/zone_templates/new.xml

Response

Example body
<zone-template>
  <custom-ns type="boolean">false</custom-ns>
  <default-ttl type="integer">900</default-ttl>
  <name nil="true"></name>
  <ns1 nil="true"></ns1>
  <ns-type>pri_sec</ns-type>
  <nx-ttl nil="true"></nx-ttl>
  <slave-nameservers></slave-nameservers>
</zone-template>

Zone templates - Create a template

Request

Example
POST /api/1.1/zone_templates.xml

<zone-template>
  <custom-ns type="boolean">false</custom-ns>
  <default-ttl type="integer">900</default-ttl>
  <name>Some Template</name>
  <ns-type>pri_sec</ns-type>
  <nx-ttl nil="true"></nx-ttl>
</zone-template>
Notes

ns1 should be left out unless ns-type is ‘sec’. slave-nameservers should be left out unless ns-type is ‘pri’. See more details under Zone Templates Overview.

Response

Example header
Location: http://ns.zerigo.com/api/1.1/zone_templates/12345679.xml
Example body
<zone-template>
  <created-at type="datetime">2010-01-26T07:43:14Z</created-at>
  <custom-nameservers></custom-nameservers>
  <custom-ns type="boolean">false</custom-ns>
  <default-ttl type="integer">900</default-ttl>
  <host-templates type="array"/>
  <host-templates-count type="integer">0</host-templates-count>
  <hostmaster nil="true"></hostmaster>
  <id type="integer">12345679</id>
  <name>Some Template</name>
  <notes nil="true"/>
  <ns-type>pri_sec</ns-type>
  <ns1 nil="true"/>
  <nx-ttl nil="true"/>
  <slave-nameservers></slave-nameservers>
  <updated-at type="datetime">2010-01-26T07:51:26Z</updated-at>
</zone-template>
Notes

Status 201 on success.
Status 422 on validation error.

Zone templates - Update a template

Request

Example
PUT /api/1.1/zone_templates/12345678.xml

<zone-template>
  <name>Some Template</name>
  <ns-type>pri_sec</ns-type>
  <default-ttl type="integer">1800</default-ttl>
  <nx-ttl nil="true"></nx-ttl>
  <custom-ns type="boolean">false</custom-ns>
</zone-template>
Notes

ns1 should be left out unless ns-type is ‘sec’. slave-nameservers should be left out unless ns-type is ‘pri’. See more details under Zone Templates Overview.

Response

Notes

Status 200 on success.
Status 422 on validation error.

Zone templates - Delete a template

Request

Example
DELETE /api/1.1/zone_templates/1234568.xml

Response

Notes

Status 200 on success.

Host templates - Overview and Fields

Host Templates are the host records that are attached to a zone template. Accordingly, they’re very similar to Hosts:

Host : Zone :: Host Template : Zone Template

Fields

created-at
Initial creation time of this resource. (readonly)
data
See Hosts Overview. In addition, for all host-types except SPF, TXT, and URL, an @ will be replaced by the domain name when the template is inherited by a domain (for example, “mail.@” becomes “mail.domain.com”). (required; read/write)
host-type
DNS host record type; see Hosts Overview. (required; read/write)
hostname
Any part of a domain in front of the domain itself (aka a subdomain). For example, for a fully qualified domain name of ‘www.example.com’, where the zone domain is ‘example.com’, the hostname would be ‘www’. If there isn’t any hostname in front of the domain name, this should be set as nil or left out. Wildcard hostnames are supported (eg: ‘*’ or ‘*.subdomain’). (optional; read/write)
id
Unique ID for this host template. (readonly)
notes
Notes about the host template. (optional; read/write)
priority
Indicates the relative priority of two or more of certain host-types, such as MX or SRV. For example, this may be set to 10 for a primary mail server and 20 for a backup server.
ttl
TTL (time-to-live), in seconds. If nil, the record uses the default-ttl value from the zone. (optional; read/write)
updated-at
Last update time of this resource. (readonly)
zone-template-id
ID of the template to which this record is attached. (readonly)

Host templates - List host templates

Request

Example
GET /api/1.1/zone_templates/12345678/host_templates.xml?per_page=100&page=1

GET /api/1.1/host_templates.xml?zone_template_id=12345678
Notes

There are two optional parameters: page=# and per_page=#. page defaults to 1 (and starts at 1, not 0). per_page defaults to 100 but should be specified exactly if a change of the default value will cause your application to fail. The maximum value for per_page is 1000.

Response

Example header
X-Query-Count: 12
Example body
<host-templates type="array">
  <host-template>
    <created-at type="datetime">2010-01-27T07:37:05Z</created-at>
    <data>10.10.10.10</data>
    <host-type>A</host-type>
    <hostname>www</hostname>
    <id type="integer">23456789</id>
    <notes nil="true"/>
    <priority nil="true"></priority>
    <ttl nil="true"></ttl>
    <updated-at type="datetime">2010-01-27T07:37:05Z</updated-at>
    <zone-template-id type="integer">12345678</zone-template-id>
  </host-template>
<host-template>
Notes

X-Query-Count will contain the total number of results, including those that didn’t fit inside this response. For example, if there are 12 results and per_page is 10, only 10 entries will be returned but X-Query-Count will show 12 so that you know there are more results remaining.

Host templates - Count all host templates

This is the total number of host templates available for the specified zone template. It is the same result as provided in the X-Query-Count header in the Managed DNS → List host templates templates API method.

Request

Example
GET /api/1.1/zone_templates/12345678/host_templates/count.xml

GET /api/1.1/host_templates.xml?zone_template_id=12345678

Response

Example body
<count>12</count>

Host templates - Get a host template

Request

Example
GET /api/1.1/host_templates/23456798.xml

Response

Example body
<host-template>
  <created-at type="datetime">2010-01-27T07:37:05Z</created-at>
  <data>10.10.10.10</data>
  <id type="integer">23456789</id>
  <hostname>www</hostname>
  <host-type>A</host-type>
  <notes nil="true"/>
  <priority nil="true"></priority>
  <ttl nil="true"></ttl>
  <updated-at type="datetime">2010-01-27T07:37:05Z</updated-at>
  <zone-template-id type="integer">12345678</zone-template-id>
</host-template>

Host templates - Get a blank host template

This response may be useful to obtain a blank host template, suitable for use as a guide or retrieving default values for included fields. zone-template-id will be populated only if provided.

Request

Example
GET /api/1.1/zone_templates/12345678/host_templates/new.xml

GET /api/1.1/host_templates/new.xml

GET /api/1.1/host_templates/new.xml?zone_template_id=12345678

Response

Example body
<host-template>
  <data nil="true"></data>
  <hostname nil="true"></hostname>
  <host-type>A</host-type>
  <priority nil="true"></priority>
  <ttl nil="true"></ttl>
  <zone-template-id nil="true"></zone-template-id>
</host-template>

Host templates - Create a host template

Request

Example
POST /api/1.1/zone_templates/12345678/host_templates.xml

POST /api/1.1/host_templates.xml?zone_template_id=12345678

POST /api/1.1/host_templates.xml

<host-template>
  <data>10.0.0.1</data>
  <hostname>www</hostname>
  <host-type>A</host-type>
  <priority nil="true"></priority>
  <ttl nil="true"></ttl>
  <zone-template-id>12345678</zone-template-id>
</host-template>
Notes

zone-template-id is only required in the body if the zone-template-id is not available as part of the URL.

hostname, priority, and ttl may be left out entirely if their value is nil.

Response

Example header
Location: http://ns.zerigo.com/api/1.1/zone_templates/12345678/host_templates/23456789.xml
Example body
<host-template>
  <created-at type="datetime">2010-01-27T07:37:05Z</created-at>
  <data>10.10.10.10</data>
  <id type="integer">23456789</id>
  <hostname>www</hostname>
  <host-type>A</host-type>
  <notes nil="true"/>
  <priority nil="true"></priority>
  <ttl nil="true"></ttl>
  <updated-at type="datetime">2010-01-27T07:37:05Z</updated-at>
  <zone-template-id type="integer">12345678</zone-template-id>
</host-template>
Notes

Status 201 on success.
Status 422 on validation error.

Host templates - Update a host template

Request

Example
PUT /api/1.1/host_templates/23456789.xml

<host-template>
  <hostname>www</hostname>
  <host-type>A</host-type>
  <ttl>10800</ttl>
  <priority nil="true"></priority>
  <data>10.0.0.1</data>
</host-template>

Response

Notes

Status 200 on success.
Status 422 on validation error.

Host templates - Delete a host template

Request

Example
DELETE /api/1.1/host_templates/23456789.xml

Response

Notes

Status 200 on success.

Tools - Overview and Fields

These are small utility methods that don’t belong anywhere else.

Fields

ipv4
An IPv4 address.

Tools - Get the current public IP

If you’re doing development or production behind NAT devices, it may be helpful to retrieve your current public IP address.

Request

Example
GET /api/1.1/tools/public_ipv4.xml

Response

Example body
<ipv4>64.27.57.4</ipv4>