DNS Management via the API

Creating and Updating DNS Zones and Records

Creating and Updating DNS

Updating records is similar to querying them. The main differences are:

  1. Attributes that are to be updated are sent in JSON format.
  2. A PUT HTTP request for updating records and a POST request is used for creating new records.

  3. Creating and Updating DNS Zone Information

    The table below indicates what attributes may be updated and those that can be specified on zone creation.

    Attribute Update (PUT) Create (POST) Description
    ID No No System generated unique Identifier
    domain No Yes* Domain name
    type Yes Yes Native, Master, Slave mode
    master_server Yes Yes Change the master server (slave mode only)
    template_id No No Template ID – set when a zone is created from a template.
    soa_admin Yes Yes Email address of the person in charge of the zone.
    soa_expiry Yes Yes Slaves stop responding to queries for the zone when this time (in seconds) has expired and no contact has been made with the master.
    soa_minimum Yes Yes The default TTL (time-to-live) for resource records, how long data will remain in other nameserver's cache.
    soa_ns Yes Yes Primary master nameserver. Any name server that will respond authoritatively for the domain.
    soa_refresh Yes Yes Interval for the slave to try to refresh the zone from the master.
    soa_retry Yes Yes Interval between retries if the slave (secondary) fails to contact the master when refresh has expired.
    soa_serial Yes Yes Incremental serial number – automatically updated on record change.

    *Mandatory when creating a new zone.

    To create a new zone, the POST method is used:

    Verb: POST
    Action: /api/dns/v1/domains
    Parameters: JSON-formatted set of attributes to be modified.
    Returns: JSON response (as documented below).

    To update an existing zone, the PUT method is used in a similar way:

    Verb: PUT
    Action: /api/dns/v1/domains/<domain name | ID>
    Parameters: JSON-formatted set of attributes to be modified.
    Returns: JSON response (as documented below).

    JSON Response

    The following JSON response is returned on execution of the API call. The response will provide both a success/fail response and provide details about any failed validation. The response also returns the newly generated ID if creating a zone.

    {
        "id": "", 
        "message": "Created  OK.", 
        "result": "true"
    }
    

    The result is similar for a PUT (update) request appears as:

    {
        "message": "Update OK", 
        "result": "true"
    }
    

    The attributes returned are as follows:

    Attribute Description
    ID The unique identifier for the resource record created. Only sent on successful creation.
    message Response message – includes any validation information for invalid attributes.
    result True/false response to indicate successful creation.

    Creating and Updating DNS Records

    Creating an updating Resource Records (RRs) is managed in a similar fashion to managing zones.

    Attributes that are sent as parameters are as follows:

    Attribute Update (PUT) Create (POST) Description
    ID No No System generated unique Identifier.
    name Yes Yes* Name of the record (e.g. “www” – no not specify the FQDN).
    type Yes Yes* The RR type (MX, CNAME, A, AAAA etc).
    value Yes Yes* Value associated with the record.
    ttl Yes Yes The default TTL (time-to-live) for the record – how long data will remain in other nameserver's cache.
    prio Yes Yes Record Priority – typically only used with MX records.
    template_id No No If the zone belongs to a template, indicate the template ID.
    template_record_id No No If the zone belongs to a template, indicate the template’s corresponding record ID.

    *Mandatory when creating a new resource record.

    To create a new Resource Record:

    Verb: POST
    Action: /api/dns/v1/domains/<domain name | ID>/records
    Parameters: JSON-formatted set of attributes to be modified.
    Returns: JSON response (as documented below).

    To update an existing Resource Record:

    Verb: PUT
    Action: /api/dns/v1/domains/<domain name | ID>/records/
    Parameters: JSON-formatted set of attributes to be modified.
    Returns: JSON response (as documented below).

    JSON Response

    The following JSON response is returned on execution of the API call. The response will provide both a success/fail response and provide details about any failed validation. The response also returns the newly generated ID if creating a new record.

    {
        "id": "<ID>", 
        "message": "Created record OK", 
        "result": "true"
    }
    

    Setting a record with the client’s IP address

    If the value of an A or AAAA record is set to “self”, the value of the record is set to the client’s IP address. Care should be taken to ensure that the client is connecting over IPv4 when updating/creating an A record or IPv6 when updating/creating an IPv6 record.


    Retrieving DNS Records from the API Deleting DNS Zones and Records