.. role:: green

Domain Records
==============

Manage domain name records via API.


Create Domain Record
--------------------

**Type:** :guilabel:`POST`

.. py:function:: https://cloud.syminet.com/api/v1/domains/{DOMAIN_ID}/records/create

    Create new DNS record for domain ``DOMAIN_ID``

**Required URL Parameters:**

DOMAIN_ID
  Domain ID for domain.

**Required JSON Properties:**

type
  DNS record ``type`` is *always* required.  

Record types have different JSON properties.  They are described in the below examples 
for each currently supported type.

.. Note::

   TTL ("Time To Live") values are an integer in seconds.  If not provided, the default is 7200
   (2 hours).  Minimum is 30.  For the sake of brevity, we only show a ``ttl`` property in the JSON 
   example for ``A`` records below, of 1200 (20 minutes).  However, a TTL can be provided for 
   **all** record types.   


A Record
~~~~~~~~

A record properties:

name
  FQDN ("Fully Qualified Domain Name"), e.g. ``example.com``

target
  IP Address the name points to.

We provide two examples here.  First, the ``A`` record for the root domain ``example.com`` itself:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "A",
            "name": "example.com",
            "target": "192.168.2.3",
            "ttl": 1200
         }
         '

Now that the root ``A`` record is created, we create a ``www`` subdomain for it pointing to the 
same ``target`` IP address:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "A",
            "name": "www.example.com",
            "target": "192.168.2.3",
            "ttl": 1200
         }
         '

.. Hint:: 

   Multiple ``A`` records with the same ``name`` are supported, so long as they have a unique ``target`` 
   (IP Address).  If multiple ``A`` records exist, the nameservers will respond in "round robin" 
   fashion, creating a very basic form of load balancing.

**Response:** :green:`202 OK`


CAA Record
~~~~~~~~~~

CAA record properties: 

name
  FQDN ("Fully Qualified Domain Name"), e.g. ``example.com``

tag
  "issue", "issuewild" or "iodef"

target
  CA ("Certificate Authority") allowed to issue certificates, e.g. ``letsencrypt.org``

.. Hint::

   Multiple CAA records are supported, in case you want to allow different CA's to be able to 
   provide different certificate types.

``CAA`` record for ``example.com`` allowing certificates to be issued from ``letsencrypt.org``:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "CAA",
            "name": "example.com",
            "tag": "issuewild",
            "target": "letsencrypt.org"
         }
         '

**Response:** :green:`202 OK`


CNAME Record
~~~~~~~~~~~~

CNAME record properties:

name
  FQDN ("Fully Qualified Domain Name"), e.g. ``www.example.com``

target
  FQDN that *points to* ``name``, e.g. ``www2.example.com``

``CNAME`` record to forward ``www2.example.com`` to ``www.example.com``:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "CNAME",
            "name": "www2.example.com",
            "target": "www.example.com"
         }
         '

**Response:** :green:`202 OK`


MX Record
~~~~~~~~~

MX record properties:

name
  FQDN for mail (part after the @ in email,  e.g. ``example.com``)

priority
  Integer priority value.  If omitted, defaults to :guilabel:`10`.    

target
  FQDN that hosts email for ``name``, e.g. ``mail.example.com``

.. Note::

   Make sure your ``target`` has an ``A`` record as well, so it can resolve to an 
   IP address.

``MX`` record to spcify ``mail.example.com`` as the mailserver for ``example.com``:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "MX",
            "priority": 10,
            "name": "example.com",
            "target": "mail.example.com"
         }
         '

**Response:** :green:`202 OK`


NS Record
~~~~~~~~~

NS record properties:

name
  FQDN *subdomain* to delegate DNS to, e.g. ``subdomain.example.com``

target
  FQDN of DNS server for ``name``, e.g. ``ns1.example.com``

``NS`` record to delegate nameservice for ``subdomain.example.com`` to ``ns1.example.com``:

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "NS",
            "name": "subdomain.example.com",
            "target": "ns1.example.com"
         }
         '

**Response:** :green:`202 OK`


SRV Record
~~~~~~~~~~

SRV record properties:

name
  Service name, e.g. ``www``

protocol
  Protocol, e.g. "tcp", "udp"

priority
  Integer value between 0 and 65535

weight
  Integer value between 0 and 65535

port
  Integer value between 0 and 65535

target
  FQDN, e.g. ``example.com`` or **@** for root.

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "SRV",
            "name": "www",
            "protocol": "tcp",
            "priority": "10",
            "weight": "5",
            "port": "80",
            "target": "example.com"
         }
         '

**Response:** :green:`202 OK`


SSHFP Record
~~~~~~~~~~~~

SSHFP record properties:

name
  FQDN ("Fully Qualified Domain Name"), e.g. ``example.com``

sshfp_algorithm
  Integer value between 0 and 255

sshfp_type
  Integer value between 0 and 255 

target
  SSH Fingerprint

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "SSHFP",
            "name": "example.com",
            "sshfp_algorithm": "1",
            "sshfp_type": "1",
            "target": "72d30d211ce8c464de2811e534de23b9be9b4dc4"
         }
         '

**Response:** :green:`202 OK`


TXT Record
~~~~~~~~~~

TXT record properties:

name
  FQDN ("Fully Qualified Domain Name"), e.g. ``example.com``

target
  Response text, free form string.  Max length 254 characters.

.. Hint::

   TXT records are often used to create SPF and DKIM records.  They are also 
   commonly used by third party services to verify domain ownership.

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/create \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "TXT",
            "name": "example.com",
            "target": "This is the TXT record for example.com"
         }
         '

**Response:** :green:`202 OK`


.. _List Domain Records:

List Domain Records
-------------------

**Type:** :guilabel:`GET`

.. py:function:: https://cloud.syminet.com/api/v1/domains/{DOMAIN_ID)

    Return details of domain ``DOMAIN_ID``, including all records.

**Required URL Parameters:**

DOMAIN_ID
  Domain ID of domain to fetch.

.. code-block:: shell
   :caption: Curl

    curl --request GET \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID \
         --header "authorization:bearer $API_TOKEN"

.. code-block:: json
    :caption: Response

    {
      "data" : [
        {
          "comments" : [],
          "name" : "example.com.",
          "records" : [
            {
              "content" : "192.168.2.3",
              "disabled" : false
            }
           ],
           "ttl" : 3600,
           "type" : "A"
        },
        {
          "comments" : [],
          "name" : "www.example.com.",
          "records" : [
            {
              "content" : "192.168.2.3",
              "disabled" : false
            }
           ],
           "ttl" : 3600,
           "type" : "A"
        }
      ]
    }


Delete Domain Record
--------------------

**Type:** :guilabel:`DELETE`

.. py:function:: https://cloud.syminet.com/api/v1/domains/{DOMAIN_ID}/records/delete

    Delete a domain record from domain ``DOMAIN_ID``.

**Required URL Parameters:**

DOMAIN_ID
  Domain ID for domain to delete record from.

**Required JSON Properties:**

type
  Record ``type`` e,g, ``A``, ``MX``, ``CNAME`` etc.

name
  Name property, e.g. "www.example.com"

target
  Target property of the record, e.g. IP Address for ``A`` records.

.. Important::

    ``target`` needs to *exactly match* the ``content`` property for the record, as shown in the 
    :ref:`List Domain Records` API call.  For example, when deleting an MX record you might 
    supply a ``target`` of ``"10 mail.example.com"`` 

.. Note::

   ``TXT`` and ``CAA`` records contain quotes wich must be escaped in ``target``.  For example 
   ``TXT`` record content is enclosed in quotes, so you can use something like the following:
   
   ``"target": "\"This is the text record\""``  
   
   ``CAA`` records also use quotes, but only for the CA field.  So for those you might use: 
   
   ``"target": "0 issuewild \"letsencrypt.org\""``

   When in doubt, you can always get the correct ``content`` value (including escaped quotes)
   by using a :ref:`List Domain Records` API call.

.. code-block:: shell
    :caption: Curl

    curl --request DELETE \
         --url https://cloud.syminet.com/api/v1/domains/DOMAIN_ID/records/delete \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "type": "A",
            "name": "example.com",
            "target": "192.168.2.3"
         }
         '

**Response:** :green:`202 OK`