REST API v1.1 - Managed DNS

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.