DDNS: Part 4 – Using the Application Programmers Interface

Audience

This article is for users who seek to access the Same Day Rules Dynamic Domain Name System (DDNS) API either through an existing network tool such as curl or through a custom update utility of their own. Other users may wish to download one of the existing DDNS Update Clients (DUC’s) available here.

DDNS API

The Same Day Rules DDNS API is based upon the standard established by Dyn as documented here. It currently implements the (legacy) update function documented on the Dyn website here. The API is also very closely related to that used by DNS-O-Matic given here.

The Same Day Rules DDNS API is detailed below.

DDNS API URL

The DDNS API URL endpoint is:

https://samedayrules.net/api/v1/nic/update

Rules for Accessing the API

The following rules for accessing the API are adapted from both the Dyn and DNS-O-Matic standards.

1. HHTP Request

Update requests must be sent using HTTPS on port 443. Example:

Hostname: samedayrules.net
HTTPS port: 443

2. HTTP User-Agent Header

All clients must send a well-formed User-Agent HTTP header including company name, model number, and software build revision. Example:

SameDayRules - CURL Update Test - 1.0

3. (Legacy) URL

The legacy URL is used. Example:

https://{username}:{password}@samedayrules.net/api/v1/nic/update?hostname={hostnames}&myip={ipaddress}&offline={status} &wildcard=NOCHG&mx=NOCHG&backmx=NOCHG

Password is the client access key as given on the Manage DDNS Service account page, and not user login password to the Same Day Rules website.

4. Authentication in URL

Base64-encoded authorization should be represented by base64 encoded username:password string sent using the “special” URL format. The authentication type must be set to Basic. Example:

https://username:password@samedayrules.net/

This sends the credentials in the standard HTTP Authorization header.

5. Hostname Parameter

Comma separated list of hostnames that you wish to update (up to 20 hostnames per request). Hostnames are fully qualified domain names (minus the trailing period). This is a required field.

Each hostname specified will be updated with the same information, and the return codes will be given one per line, in the same order as given. Example:

hostname=cam1.samedayrules.net,weather1.samedayrules.net

6. Myip Parameter

IP address to set for the update. The single IP address is applied to all hostnames.

If this parameter is not specified, the best IP address the server can determine will be used (some proxy configurations pass the IP in a header, and that is detected by the server). If the IP address passed to the system is not properly formed, it will be ignored and the system’s best guess will be used.

7. Offline Parameter

Status applied to the hostname (i.e., YES, NO, NOCHG) indicating whether or not the specified hostname should be considered inactive/active.

YES indicates that the hostname should be made inactive (offline) such that references to it do not return a logical value. DNS queries to an inactive hostname will either fail or will return a default value.

NO indicates that the hostname should be made active (online) such that references to it return the associated IP address via DNS queries.

NOCHG will not change the status of the hostname (if the hostname was active it will remain that way, if the hostname was inactive it will remain that way).

Note that if the offline parameter is not supplied in the API call, then the hostname will be made active.

8. Remaining Parameters (wildcard, mx, backmx)

The remaining parameters (wildcard, mx, and backmx) are ignored. They can be sent in the API request, but the parameters and their values are ignored. Their inclusion is for backward compatibility with existing DDNS update clients.

9. Return Codes

As per DNS-O-Matic with additions for extra granularity on failures.

HTTP request return code 200 for all good commands.

HTTP request return code 400 for all failed commands.

A summary of return codes is given below:

Code	Request Body Text	Meaning
200	good ip	Update was successful for the given hostname; applied ip address returned.
400	badrequest	Error occurred at the HTTP request level (possible bad incoming IP address).
400	badagent	User-Agent HTTP header field is missing or malformed.
400	badauth	Authentication type is invalid or the username:password pair does not authenticate.
400	baduser	Username is either unrecognized or identifies an inactive service subscriber.
400	nohost	Hostname is missing or is not associated with supplied username.
400	numhost	Number of hostnames supplied is greater than the maximum allowed.
400	notfqdn	Hostname is a not a fully qualified domain name (x.y.z).
400	dnserr	Update failed at the DNS server level.
400	911	Unknown error occurred at the DDNS update level.

Example Using curl

The following is an example call to the API using curl (for the user “iotmax”):

curl -i -X GET -H "User-Agent: SameDayRules - CURL Update Test - 1.0" -u "iotmax:f610y694w854k3a55d0hy69sit65307m" -sS "https://samedayrules.net/api/v1/nic/update?hostname=cam1.samedayrules.net&myip=67.102.100.122&wildcard=NOCHG&mx=NOCHG&backmx=NOCHG"

curl encodes the username:password field as a base64-encoded string, and adds this field as a Basic authentication header to the HTTP request.

Example Using Python

The following Python snippet shows how to properly encode the username:password field and make an HTTP Get request:

import base64

def base64_encode(user_name, access_key):
    input_string = user_name + ':' + access_key
    input_string_bytes = input_string.encode('utf-8')
    base64_bytes = base64.b64encode(input_string_bytes)
    return base64_bytes.decode('ascii')

auth = base64_encode(user_name, access_key)
url = 'https://samedayrules.net/api/v1/nic/update'
headers = {
    'User-Agent': 'SameDayRules - DDNS Update Client - 1.0',
    'Authorization': 'Basic {}'.format(auth)
}
params = {'hostname': hostname, 'myip': ip_address}
response = requests.get(url=url, headers=headers, params=params)

Update Frequency

Update clients must not exceed more than one update per 30 seconds. Authenticated users specified in update calls from clients exceeding this limit will be classified as abusing the service and will be set as INACTIVE. Users classified as inactive must contact Same Day Rules in order to re-activate their account.