GANDI

LiveDNS API

Table of Contents

Introduction

LiveDNS is Gandi's upcoming DNS platform, a completely new service that offers its own API and its own nameservers.

The new platform offers powerful features to manage DNS Zone templates that you can integrate into your own workflow. Features include bulk record management, association with multiple domains, versioning and rollback.

This document describes the RESTful HTTP API, including a simple example to get you started.

Getting started

Requirements

A Gandi API token
An HTTP client

Quick example

This example will show you how to create a Zone file to point the "www.example.com" and "example.com" addresses to the same IPV4 address and then associate your new Zone file with the domain.

To keep things simple and universal, the snippets use curl from the command line to make HTTP requests to the LiveDNS API. You can of course use any other tool to make the equivalent requests.

Step 1 - Get your API key

Start by retrieving your API Key from the "Security" section in new Account admin panel to be able to make authenticated requests to the API.

Step 2 - Create your Zone file

Make a POST request to the /zones endpoint to create your Zone file.

You only need to set the name property to something that makes sense for you and let the platform use the default values for the rest (you can change them later if you want).

Example:

$ curl -D- -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"name": "example.com Zone"}' \
             https://dns.api.gandi.net/api/v5/zones

HTTP/1.1 201 Created
Server: nginx
Date: Mon, 28 Dec 2015 13:23:56 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 27
Connection: keep-alive
Location: https://dns.api.gandi.net/api/v5/zones/93cc9312-a214-408b-a75b-9d4172984746

{"message": "Zone Created"}

Note that the URI of the Zone file you have just created is available in the Location: header and that it includes the resource's uuid, which you can parse in a script.

Throughout these examples, the -D- flag is passed to curl to write the HTTP response headers to STDOUT.

Just a quick note - Shortcut access to a domain's zone

Note that if you don't want to handle zones, and simply want the shortest route to modify a domain's zone, you can also access the zone records using the following shortcut, which is equivalent to accessing /zone/<uuid>/records:

Example:

$ curl -H"X-Api-Key: $APIKEY" \
    https://dns.api.gandi.net/api/v5/domains/example.com/records

More information is available below, in the Work with Domains section.

Step 3 - Create the DNS records

The LiveDNS API is pretty flexible and allows you to create DNS records in a few different ways. In this example, you'll use a single PUT request to the /zones/<uuid>/records endpoint to create two DNS records, described as JSON objects.

Example:

$ curl -D- -X POST -H "Content-Type: application/json" \
        -H "X-Api-Key: $APIKEY" \
        -d '{"rrset_name": "www",
             "rrset_type": "A",
             "rrset_ttl": 3600,
             "rrset_values": ["192.168.0.1"]}' \
        https://dns.api.gandi.net/api/v5/zones/93cc9312-a214-408b-a75b-9d4172984746/records


HTTP/1.1 201 Created
Server: nginx
Date: Mon, 28 Dec 2015 13:55:43 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 34
Connection: keep-alive
Location: https://dns.api.gandi.net/api/v5/zones/93cc9312-a214-408b-a75b-9d4172984746/records/www/A

{"message": "Zone Record Created"}

Now your zone file contains two A records that point www and @ to the same IP address, with TTL values of 3600 seconds (1 hour).

You can also overwrite the whole zone using text/plain data (following the a limited subset of the RFC 1035 master file format):

$ curl -D- -XPUT -H "Content-Type: text/plain" \
    -H"X-Api-Key: $APIKEY" \
    --data-binary @- \
    https://dns.api.gandi.net/api/v5/zones/93cc9312-a214-408b-a75b-9d4172984746/records \
    << EOF
www IN A 192.168.0.1
    IN A 192.168.0.2
@   IN MX 10 spool.mail.gandi.net.
EOF

Step 4 - Associate the domain

Now it's time to associate your domain, example.com, with this Zone file. In this example you'll use the /zones/<uuid>/domains/<domain> endpoint, as it offers the simplest possible code snippet, but you can find different ways to accomplish this in the API reference.

Example:

curl -D- -X POST -H "Content-Type: application/json" \
                -H "X-Api-Key: $APIKEY" \
                https://dns.api.gandi.net/api/v5/zones/93cc9312-a214-408b-a75b-9d4172984746/domains/example.com

HTTP/1.1 201 Created
Server: nginx
Date: Mon, 28 Dec 2015 18:06:04 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 29
Connection: keep-alive
Location: https://dns.api.gandi.net/api/v5/domains/example.com

{"message": "Domain Created"}

Step 5 - Change your nameservers

And with that you're ready to go. If you change the nameservers, this new zone will be live for the whole Internet to see. Before you do this, make sure you copy all the records from your current DNS service.

Each domain has a unique set of nameservers. You have to query our API to grab your set of nameservers:

curl https://dns.api.gandi.net/api/v5/nameservers/example.com

Step 6 - setup automatic DNSSEC signing

By posting to /domains/<fqdn>/keys, you can create a DNSKEY and have our servers automatically sign the zone for you:

Example:

$ curl -v -X POST -H 'Content-Type: application/json' \
    -d '{"flags": 257}' -H "X-Api-Key: $APIKEY" \
    https://dns.api.gandi.net/api/v5/domains/example.com/keys

You then have access to the key's DS and information by GETting the key array. Keys are accessed using their key_href like so:

Getting the key href:

$ curl -H"X-Api-Key: $APIKEY" \
    https://dns.api.gandi.net/api/v5/domains/example.com/keys |
    jq .[].key_href

Deleting the key:

$ curl -H"X-Api-Key: $APIKEY" -X DELETE \
    https://dns.api.gandi.net/api/v5/domains/example.com/keys/bb004a38-566b-4200-bd6e-830b48ea50cf

WARNING: you should never delete a key if a DS is present at the registry, or still present in the caches, as it would make the zone "security lame". If you mistakenly do so, you can recover the key by using a PUT method on its uuid:

$ curl -H"X-Api-Key: $APIKEY" -X PUT \
    -H'Content-Type: application/json' \
    -d '{"deleted": False}' \
    https://dns.api.gandi.net/api/v5/domains/example.com/keys/bb004a38-566b-4200-bd6e-830b48ea50cf

Step 7 - Adding extra security with a slave server

Note

This is a new feature - Please send us your feedback at : feedback <at> gandi <dot> net

We strive to provide you with the best DNS service ever, but having all your eggs in one basket is not best practice. Our servers will happily accept AXFR requests from slave configured with the right TSIG key. Bonus, they'll also send NOTIFY packets to the slaves you configured. We do not support pure IPv4 ACLs yet, you have to use TSIG, but it's pretty common nowadays.

First, create a TSIG key - you might want to share it among multiple domains later:

Creating a TSIG key:

$ curl -XPOST -H"X-Api-Key: $APIKEY" \
    https://dns.api.gandi.net/api/v5/axfr/tsig

{"key_name": "85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net", "secret": "0ghpfTvSgQ+n3sb56y1Wc4TydiCLBiunLmsy2LtSTqU3MQ5KaMsxbShPoyyzORC8grAE8++CAYPPGRnf+YylIg==", "uuid": "85e7b6e3-4553-479b-b968-cd0c77143802", "axfr_tsig_url": "https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802"}

Then, use the key uuid to authorize AXFRs on your domain like so:

Adding the TSIG key for AXFRs:

$ curl -H"X-Api-Key: $APIKEY" \
    -XPUT https://dns.api.gandi.net/api/v5/domains/example.com/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802

Now, if you also want to notify slave servers, you can add them to the domain configuration via the /axfr/slaves route like so:

Adding two slaves servers to the domain:

$ for host in 198.51.100.1 2001:DB8::1; do curl -H"X-Api-Key: $APIKEY" \
    -XPUT https://dns.api.gandi.net/api/v5/domains/example.com/axfr/slaves/$host ; done

And voila, your domain is now replicated to a second host.

DNSSEC RRSIG records are generated along with NSEC3 records if you enabled DNSSEC.

Simply updating the zone records should generate a NOTIFY message to the configured slaves. We'll buffer that through a 30 seconds window to avoid notification storms.

Bonus, if you're setting up the slave on your own server, we provide you with configuration samples including the master servers IPs, and all the TSIG configuration.

Simply fetch the TSIG key from axfr/tsig and follow the config_samples dict for your software:

 $ curl -H"X-Api-Key: $APIKEY" https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802
 { ... "config_samples": {"powerdns": "https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/powerdns", "bind": "https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/bind", "nsd": "https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/nsd", "knot": "https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/knot"} ... }

 $ curl -H"X-Api-Key: $APIKEY" -H'Accept: text/plain' \
     https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/bind

key 85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net {
     algorithm hmac-sha512;
     secret "...";
};

master 217.70.177.41 {
};

master 217.70.186.167 {
};

zone "example.com" {
 type slave;
 file "example.com";
 masters {  217.70.177.41 key 85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net; 217.70.186.167 key 85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net; };
};

zone "example.net" {
  type slave;
  file "example.net";
  masters {  217.70.177.41 key 85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net; 217.70.186.167 key 85e7b6e3-4553-479b-b968-cd0c77143802.gandi.net; };
};

Or if you use Powerdns:

$ curl -H"X-Api-Key: $APIKEY" -H'Accept: text/plain' \
    https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/powerdns
[...]

Or if you use Knot:

$ curl -H"X-Api-Key: $APIKEY" -H'Accept: text/plain' \
    https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/knot
[...]

Or if you use Nsd:

$ curl -H"X-Api-Key: $APIKEY" -H'Accept: text/plain' \
    https://dns.api.gandi.net/api/v5/axfr/tsig/85e7b6e3-4553-479b-b968-cd0c77143802/config/nsd
[...]

Reference

API Endpoint

The LiveDNS API is currently available at:

https://dns.api.gandi.net/api/v5/

Resources

Zone

uuid
name
primary_ns
email
serial
refresh
retry
expire
minimum

ZoneRecord

rrset_name
rrset_type (from RecordType)
rrset_ttl
rrset_values (list of values)

RecordType

One of :

A, AAAA, CAA, CDS, CNAME, DNAME, DS, LOC, MX, NS, PTR, SPF, SRV, SSHFP, TLSA, TXT, WKS.

Domain

fqdn
zone_uuid

Snapshot

serial
zone_uuid
change_time
zone_data

Usage

Work with Zones

Managing Zones

List

GET /zones:

curl -H "X-Api-Key: $APIKEY" https://dns.api.gandi.net/api/v5/zones

return:

[{"retry": 3600,
  "uuid": "<UUID>",
  "minimum": 10800,
  "refresh": 10800,
  "expire": 604800,
  "serial": 1432798405,
  "user_uuid": "<USER_UUID>",
  "email": "hostmaster.gandi.net.",
  "primary_ns": "a.dns.gandi.net.",
  "name": "<NAME>"}]

count number is in headers:

X-Total-Count: 1

Create a zone with name NAME

POST /zones:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"name": "<NAME>"}' \
             https://dns.api.gandi.net/api/v5/zones

return:

{"message": "Zone Created"}

location is in headers:

Location: /zones/<UUID>

Note: You can only associate domains and zones that share the same organization or, "sharing space". Therefore, If you want to create a new zone and attach it to a domain that is in an organization (ie. not your personal account), you must create the zone with the same SHARING_ID of the domain.

Unfortunately, there is no API that returns the SHARING_ID.To find the SHARING_ID, you must use the v5 website and navigate to the dashboard of the organization that owns the domain. The sharing_id will be in the URL and will immediateliy follow /dashboard/.

You then need add the SHARING_ID to the URL when you send the POST command.

Example:

"https://dns.beta.gandi.net/api/v5/zones?sharing_id=$SHARING_ID"

Info for zone UUID

GET /zones/<UUID>:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>

return:

{"retry": 3600,
 "uuid": "<UUID>",
 "minimum": 10800,
 "refresh": 10800,
 "expire": 604800,
 "serial": 1432798405,
 "user_uuid": "<USER_UUID>",
 "email": "hostmaster.gandi.net.",
 "primary_ns": "a.dns.gandi.net.",
 "name": "<NAME>"}

Update zone UUID

PATCH /zones/<UUID>:

curl -X PATCH -H "Content-Type: application/json" \
              -H "X-Api-Key: $APIKEY" \
              -d '{"name": "<NAME>"}' \
              https://dns.api.gandi.net/api/v5/zones/<UUID>

return:

{"message": "Request Accepted"}

Delete zone UUID

DELETE /zones/<UUID>:

curl -X DELETE -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/zones/<UUID>

Get domains attached to zone UUID

GET /zones/<UUID>/domains:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/domains

return:

[{"fqdn": "<DOMAIN>"}]

count number is in headers:

X-Total-Count: 1

Attach a domain to zone UUID

POST /zones/<UUID>/domains/<DOMAIN>:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             https://dns.api.gandi.net/api/v5/zones/<UUID>/domains/<DOMAIN>

return:

{"message": "Domain Created"}

location is in headers:

Location: /domains/<DOMAIN>

Managing Records

List zone UUID records

GET /zones/<UUID>/records:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/records

return:

[{"rrset_type": "<TYPE>",
  "rrset_ttl": 10800,
  "rrset_name": "<NAME>",
  "rrset_values": ["<VALUE>"]}]

count number is in headers:

X-Total-Count: 1

Retrieve a text version of the zone

GET /zones/<UUID>/records:

curl -H "X-Api-Key: $APIKEY" -H 'Accept: text/plain' \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/records

return:

@ 10800 IN SOA ns1.gandi.net. hostmaster.gandi.net. 1444327484 10800 3600 604800 10800
@ 10800 IN NS ns1.gandi.net.
@ 10800 IN NS ns2.gandi.net.
@ 10800 IN NS ns3.gandi.net.
@ 86400 IN TXT "I am a TXT record"

Add a record "NAME" with type "TYPE" to the zone UUID

POST /zones/<UUID>/records:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_name": "<NAME>",
                  "rrset_type": "<TYPE>",
                  "rrset_ttl": 10800,
                  "rrset_values": ["<VALUE>"]}'
             https://dns.api.gandi.net/api/v5/zones/<UUID>/records

POST /zones/<UUID>/records/<NAME>:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_type": "<TYPE>",
                  "rrset_ttl": 10800,
                  "rrset_values": ["<VALUE>"]}' \
             https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>

POST /zones/<UUID>/records/<NAME>/<TYPE>:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_ttl": 10800,
                  "rrset_values": ["<VALUE>"]}' \
             https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>/<TYPE>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>/<TYPE>

Change all zone UUID records (application/json)

PUT /zones/<UUID>/records:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"items": [{"rrset_name": "<NAME1>",
                            "rrset_type": "<TYPE1>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE1>"]},
                           {"rrset_name": "<NAME2>",
                            "rrset_type": "<TYPE2>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE2>"]}]}' \
            https://dns.api.gandi.net/api/v5/zones/<UUID>/records

Change all zone UUID records (text/plain)

PUT /zones/<UUID>/records:

curl -X PUT -H "Content-Type: text/plain" \
            -H "X-Api-Key: $APIKEY" \
            -d '<NAME1> [<TTL>] IN <TYPE1> <VALUE1>\n...' \
            https://dns.api.gandi.net/api/v5/zones/<UUID>/records

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records

Change all "NAME" records from the zone UUID

PUT /zones/<UUID>/records/<NAME>:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"items": [{"rrset_type": "<TYPE1>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE1>"]},
                           {"rrset_type": "<TYPE2>",
                            "rrset_ttl": 10800,
                            "rrset_values":["<VALUE2>"]}]}' \
            https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>

Change the "NAME"/"TYPE" record from the zone UUID

PUT /zones/<UUID>/records/<NAME>/<TYPE>:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"rrset_ttl": 10800,
                 "rrset_values": ["<VALUE>"]}' \
            https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>/<TYPE>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>/<TYPE>

List all records with name "NAME" in the zone UUID

GET /zones/<UUID>/records/<NAME>:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>

return:

[{"rrset_type": "<TYPE>",
  "rrset_ttl": 10800,
  "rrset_name": "<NAME>",
  "rrset_values": ["<VALUE>"]}]

List all records with name "NAME" and type "TYPE" in the zone UUID

GET /zones/<UUID>/records/<NAME>/<TYPE>:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>/<TYPE>

return:

{"rrset_type": "<TYPE>",
 "rrset_ttl": 10800,
 "rrset_name": "<NAME>",
 "rrset_values": ["<VALUE>"]}

Remove the record "NAME" with type "TYPE" from the zone UUID

DELETE /zones/<UUID>/records/<NAME>/<TYPE>:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>/<TYPE>

Remove all records "NAME" from the zone UUID

DELETE /zones/<UUID>/records/<NAME>:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/zones/<UUID>/records/<NAME>

Remove all records from the zone UUID

DELETE /zones/<UUID>/records:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/zones/<UUID>/records

Using Snapshots

Create a new snapshot for zone UUID

POST /zones/<UUID>/snapshots:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             https://dns.api.gandi.net/api/v5/zones/<UUID>/snapshots

return:

{
 "message": "Zone Snapshot Created",
 "uuid": "<SNAPSHOT-UUID>"
}

List snapshots for zone UUID

GET /zones/<UUID>/snapshots:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/zones/<UUID>/snapshots

return:

[
 {
  "uuid": "<SNAPSHOT-UUID>",
  "date_created": "2016-12-16T16:51:26Z"
 }
]

Get a snapshot contents:

GET /zones/<UUID>/snapshots/<SNAPSHOT-UUID>:

curl -H "X-Api-Key: $APIKEY" \
         https://dns.api.gandi.net/api/v5/zones/<UUID>/snapshots/<SNAPSHOT-UUID>

return:

{
 "date_created": "2016-12-16T16:51:26Z",
 "uuid": "<SNAPSHOT-UUID>",
 "zone_uuid": "<UUID>",
 "zone_data": [
  {
   "rrset_type": "A",
   "rrset_ttl": 10800,
   "rrset_name": "www",
   "rrset_values": ["10.0.1.42"]
   }
  ]
}

Work with Domains

Add a domain "DOMAIN" to the zone UUID

POST /domains:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"fqdn": "<DOMAIN>",
                  "zone_uuid": "<UUID>"}' \
             https://dns.api.gandi.net/api/v5/domains

return:

{"message": "Domain Created"}

location is in headers:

Location: /domains/<DOMAIN>

List domains

GET /domains:

curl -H "X-Api-Key: $APIKEY" https://dns.api.gandi.net/api/v5/domains

return:

[{"fqdn": "<DOMAIN1>"},
 {"fqdn": "<DOMAIN2>"}]

count number is in headers:

X-Total-Count: 2

Info on domain "DOMAIN"

GET /domains/<DOMAIN>:

curl -H "X-Api-Key: $APIKEY" https://dns.api.gandi.net/api/v5/domains/<DOMAIN>

return:

{"zonedata": "/zones/<UUID>/records",
 "fqdn": "<DOMAIN>",
 "zone": "/zones/<UUID>"}

Change the zone associated to domain "DOMAIN"

PATCH /domains/<DOMAIN>:

curl -X PATCH -H "Content-Type: application/json" \
              -H "X-Api-Key: $APIKEY" \
              -d '{"zone_uuid": "<UUID>"}' \
              https://dns.api.gandi.net/api/v5/domains/<DOMAIN>

return:

{"message": "Request Accepted"}

Get records for the zone associated to domain "DOMAIN"

GET /domains/<DOMAIN>/records:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records

return:

[{"rrset_type": "<TYPE>",
  "rrset_ttl": 10800,
  "rrset_name": "<NAME>",
  "rrset_values": ["<VALUE>"]}]

count number is in headers:

X-Total-Count: 1

Get "NAME" records for the zone associated to domain "DOMAIN"

GET /domains/<DOMAIN>/records/<NAME>:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>

return:

[{"rrset_type": "<TYPE>",
  "rrset_ttl": 10800,
  "rrset_name": "<NAME>",
  "rrset_values": ["<VALUE>"]}]

count number is in headers:

X-Total-Count: 1

Get "NAME" records of type "TYPE" for the zone associated to domain "DOMAIN"

GET /domains/<DOMAIN>/records/<NAME>/<TYPE>:

curl -H "X-Api-Key: $APIKEY" \
     https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>/<TYPE>

return:

{"rrset_type": "<TYPE>",
 "rrset_ttl": 10800,
 "rrset_name": "<NAME>",
 "rrset_values": ["<VALUE>"]}

Add a record "NAME" with type "TYPE" to the zone associated to domain "DOMAIN"

POST /domains/<DOMAIN>/records:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_name": "<NAME>",
                  "rrset_type": "<TYPE>",
                  "rrset_ttl": 10800,
                  "rrset_values": ["<VALUE>"]}' \
             https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records

POST /domains/<DOMAIN>/records/<NAME>:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_type": "<TYPE>",
                  "rrset_ttl": 10800,
                  "rrset_values": ["<VALUE>"]}' \
             https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>

POST /domains/<DOMAIN>/records/<NAME>/<TYPE>:

curl -X POST -H "Content-Type: application/json" \
             -H "X-Api-Key: $APIKEY" \
             -d '{"rrset_ttl": 10800,
                  "rrset_values":["<VALUE>"]}' \
             https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>/<TYPE>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>/<TYPE>

Change all records from the zone associated with domain "DOMAIN"

PUT /domains/<DOMAIN>/records:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"items": [{"rrset_name": "<NAME1>",
                            "rrset_type": "<TYPE1>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE1>"]},
                           {"rrset_name": "<NAME2>",
                            "rrset_type": "<TYPE2>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE2>"]}]}' \
            https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records

Change all "NAME" records from the zone associated with domain "DOMAIN"

PUT /domains/<DOMAIN>/records/<NAME>:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"items": [{"rrset_type": "<TYPE1>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE1>"]},
                           {"rrset_type": "<TYPE2>",
                            "rrset_ttl": 10800,
                            "rrset_values": ["<VALUE2>"]}]}' \
            https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>

Change the "NAME"/"TYPE" record from the zone associated with domain "DOMAIN"

PUT /domains/<DOMAIN>/records/<NAME>/<TYPE>:

curl -X PUT -H "Content-Type: application/json" \
            -H "X-Api-Key: $APIKEY" \
            -d '{"rrset_ttl": 10800,
                 "rrset_values":["<VALUE>"]}' \
            https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>/<TYPE>

return:

{"message": "Zone Record Created"}

location is in headers:

Location: /zones/<UUID>/records/<NAME>/<TYPE>

Remove the record "NAME" with type "TYPE" from the zone associated to domain "DOMAIN"

DELETE /domains/<DOMAIN>/records/<NAME>/<TYPE>:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>/<TYPE>

Remove the "NAME" records from the zone associated to domain "DOMAIN"

DELETE /domains/<DOMAIN>/records/<NAME>:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records/<NAME>

Remove the records from the zone associated to domain "DOMAIN"

DELETE /domains/<DOMAIN>/records:

curl -X DELETE -H "Content-Type: application/json" \
               -H "X-Api-Key: $APIKEY" \
               https://dns.api.gandi.net/api/v5/domains/<DOMAIN>/records

Security Consideration

Using /domains api, when a zone has been attached to a domain, the owner, the admin and the technical contact of the domain can edit the domain dns zone.

In case the zone is attached on many domains, the edition of the zone by a contact of a domain will affect all attached domains.

It is the responsability of LiveDNS users to correctly share the zone between domains.