API: DNS

The dns and dns2 categories allow you to manage hosted DNS services.

Add a new DNS record to a specified zone.

Required parameters:

• zone_id - the zone ID
• name - the domain name. For example, with a zone "example.com.", both "www" and "www.example.com." equate to a record on www.example.com.
• data - the record contents, e.g. '1.2.3.4' for an A record, or 'other.example.org' for a CNAME or MX record
• ttl - record time-to-live in seconds, e.g. 1800
• type - one of 'A', 'AAAA', 'CNAME', 'ALIAS', 'MX', 'NS', 'TXT', 'SPF', 'SRV'

Optional parameters:

• aux - the priority for certain record types, like MX and SRV
• policy - the IP-based geo-targeting policy:
  • 'none' for no geo-targeting (default)
  • 'latlong' to route to records with the closest latitude/longitude to the user's estimated location
  • 'region' for hierarchical region-based routing
• weight - the record weight (this is used for load balancing or non-round-robin DNS failover)
• region, regiongroup, country, continent, global - parameters for hierarchical region-based routing; see DNS for details (set global to 'no' to disable for global group).
• latitude, longitude - latitude/longitude if policy is 'latlong'
• monitor_id - the ID of a monitor check (see monitor/check-list); this record will be disabled if the check fails
• orig_record_id - if set, update the existing record with this ID instead of creating a new record

Notes:

• If weight is non-zero for all records with a certain name and type, then two records will be returned, and the two will be selected by randomly sampling using the weight as a relative probability (i.e., a record with twice the weight will be twice as likely to be selected).
• If the weight of records with the same name and type differ by more than a factor of 100, then only the higher-weight records will be returned. However, if the higher-weight records are disabled by a monitoring check, then the lower-weight records may be returned. See DNS -> Scenario 2 (failover).

Here is an example with load-balancing for an MX record. If we repeat for mail1.orange.com, mail2.orange.com, etc., and set monitor_id appropriately, then the DNS server will randomly select two records to respond to each client query (since weight is non-zero), and failed mail servers (detected by uptime monitoring check) will not be returned.

Endpoint: dns2/record-add
zone_id=11
name=orange.com.
data=mail6.orange.com.
ttl=1800
type=MX
aux=10
weight=1
monitor_id=9898

{
    "record_id": "19831",
    "success": "yes"
}