DonDNS - Free Dynamic DNS Service

    DonDNS Documentation

    1 Introduction

    In the following page you'll find the details of the MrDomain API usage to dynamically update the registries of a DNS zone.

    MrDomain allows you to update some fields of your DNS zones with a simple GET request.

    2 Before start

    2.1 Obtaining your DonDNS Key

    The DONDNS Key is a secondary password different to the one you use to access your client zone. It is used only to operate from external applications with your MrDomain account (via API), as in the case of DonDNS, that updates the IP of the desired domain (host).

    To get your DONDNS Key, log in to your MrDomain account. On your administration panel menu click on "My Account" (it's near the "Balance" button) and then choose "DonDNS Key". If you don't have enabled your DonDNS Key, it will display the text "API disabled". You just need to click "Generate a new key" to activate it and obtain your DONDNS Key.

    Obtain DONDNS Key

    2.2 Activating the service for the domain

    Let's assume you have the domain "mydomain.com" and you want the host "home.mydomain.com" to point to your IP:

    From the "My Domains" panel, click on the hosting plan for your domain, whether it is Redirect & Parking or any other plan (it works in the same way in all of them). Once you're in the administration panel of the hosting, select "DNS Zone". At the top of the table that shows up, you'll find a button labeled "New". Choose type "A (Adress)", write "myhome" (or any name you want to use) in the "Host" field, and 127.0.0.1 in the IP address field (DonDNS will update this field).

    Finally, click "Create" and you'll have your service configured and ready to use with DonDNS.

    Get your DONDNS Key

    3 Usage

    3.1 Request

    The request must be done via HTTPS (HTTP will be discarted soon). In each request it's necessary to specify the MrDomain username and its DonDNS Key obtained on the previous procedure.

    The request must be done via GET method and the accepted parameters are the following:

    Request parameters:

    Name Required Default Description
    user Required MrDomain username
    apikey Required The DonDNS Key obtained
    host Required The entry of the DNS Zone to be updated
    ip Optional The IP address from where the request is done. The IP address to be updated
    lang Optional es The response language. es or en

    Also you can obtain the response in XML, Plain text, or JSON format. This parameter is specified on the request URL:

    https://dondns.dondominio.com/json/             For JSON
    https://dondns.dondominio.com/xml/              For XML
    https://dondns.dondominio.com/plain/            For plain text

    Request example:

    Request:

    GET https://dondns.dondominio.com/json/?user=username&password=apikey&host=home.mydomain.com&ip=108.177.219.9

    3.2 JSON response

    The obtained respnse has the following fields:

    Response fields description:

    Field Description
    success true if the request is correctly processed, false otherwise
    version The API version number
    ts Timestamp of the processing moment
    user The username in the request. If the username is not coreect, this field is not included
    messages Messages list, this field does not appear in all responses
    host The updated object. Each host has the fields specified in the next table

    Each host has the following fields:

    Response fields description:

    Field Description
    name The field of the DNS table updated
    value The IP address this field has in the DNS table
    type Type of field of the DNS table
    updated Whether the value for this field changed or not

    Resonse example for a correct request:

    Response example:

    {
        "success": true,
        "version": "2.0",
        "ts": "2016-01-21T16:06:51+01:00",
        "user": "username",
        "host": {
          "name": "home.mydomain.com",
          "value": "108.177.219.9",
          "type": "A",
          "updated": true
        },
        "messages": ["Operation done correctly."]
        }
    }

    3.3 XML response

    The obtained response has the following fields:

    Response fields description:

    Field Description
    data Root element. It's always shown.
    resData data subelement. It's shown when the username and the DonDNSKey are correct.
    host data subelement. It's shown when the host is found.
    informs data subelement. It's shown when the operation succeeds.
    errors data subelement. It's shown when the operation fails.

    data attributes:

    Field Description
    success true if the request was correctlly processed, false otherwise
    version API version number
    oper The name of the operation done.

    resData elements:

    Field Description
    user Contains the username of whom does the request. Has the t attribute, a request timestamp.
    request No value. Has the success attribute: true if the host changed the IP.

    host elements:

    Field Description
    type A host attribute. Register type in DNS table.
    name Updated DNS field.
    value The IP for the updated field.

    informs elements:

    Field Description
    inform May be more than one. Has an string with info about the updates host.

    errors elements:

    Campo Descripción
    error May be more than one. Has an string with the errors produced.

    Response example for a correct request:

    Response example:

    <?xml version="1.0" encoding="UTF-8"?>
    <data oper="dynamicip" succces="0" version="2.0">
      <informs>
        <inform>
          <![CDATA[ Operación realizada correctamente. ]]>
        </inform>
      </informs>
      <resData>
        <user t="2016-01-26T09:46:11+01:00">nombredeusuario</user>
        <request success="1"/>
      </resData>
      <host type="A">
        <name>casa.midominio.com"</name>
        <value>108.177.219.9</value>
      </host>
    </data>

    3.4 PlainText response

    The plain text response is much more simple. Is the request was successfully processed the first line of the response will be an OK.

    Response example:

    OK

    If the host IP changed, the second line of the response will be the new IP. Otherwise, there will not be a second line.

    Response example:

    OK
    UPDATE: 199.199.199.199

    In case the request produces any errors, the response's first line will be ERROR and the following lines will specify the errors.

    Response example:

    ERROR
    The message error 1
    The message error 2