dynDNS.it API

Introduction

dynDNS offers a dyndns endpoint compatible with protocol v2 and v3 of dyndns.org

The protocol has been expanded to support and overcome Browser modifications like the prohibition to embed authentication in URLs.

Here we show the full protocol accepted by dynDNS.it.

Basic Syntax

All requests must be sent to the endpoint update.dyndns.it using HTTP protocol and Basic HTTP Authentication.

The basic request is the following:

https://update.dyndns.it/nic/update?hostname=HOSTNAME

where:

• HOSTNAME is the full hostname to update (ie. myhostname.ns0.it).

IP Update

After receiving this request, dynDNS.it gets the public IP from where the request originates and sets the Hostname. In 30 seconds, the hostname starts to respond with the IP of the connection.

Response codes

The response for the request is one word followed by optional additional information.

Response	Additional Data	Example	Meaning
ok	IP Received	ok 1.2.3.4	The IP has been accepted and the hostname has been updated.
nochg	IP Received	nochg 1.2.3.4	The IP is already assigned to the Hostname. The client must send updates only when the IP changes. Sending duplicate updates is considered abusive behavior.
badauth	–	badauth	The server can not authenticate the request for the hostname using the user and password sent.
!donor	–	!donor	The action requested is reserved to active account. The account can be expired.
abuse	–	abuse	The account has been suspended due to abusive behavior
911	–	911	The server is experiencing a major issue. The client must wait 10 minutes before sending more updates.

Parameters

The request can include more parameters, all in the query string. All parameters that can be included in the request are the following. All parameters are optional, only the hostname is required.

Parameter	Values	Example	Meaning
hostname	the full hostname	hostname = myhost.ns0.it	The hostname to update. This parameter must be present in every request
myip	any public IP	myip=1.2.3.4	The IP to use to update the hostname. If not present in the request, the server will use the IP address from which the request originates
wildcard	ON or OFF	wildcard=ON	Activates/Deactivates all fourth-level domains pointing to the main hostname. For example www.myhost.ns0.it
username	valid username	username=fred	The username to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter password
password	valid password	password=1234	The password to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter username
key	valid hostkey	key=xfgt	The key authenticating the request. Used instead of the ‘Authorization’ HTTP header and the username and password parameters
mx	–	deprecated	Used in the past to assign a mail server for the hostname
system	–	deprecated	Used in the past to distinguish between dynamic and static domains

Examples

The update protocol is based on HTTP and can be easily tested using a web browser. In the following examples, you should insert the values from your account.

Update hostname using the current connection IP:

The hostname will point to the IP of the connection from where the request is sent.

    https://update.dyndns.it/nic/update?hostname=HOSTNAME

Update hostname with explicit IP to use:

The hostname will point to the IP sent.

    https://update.dyndns.it/nic/update?hostname=HOSTNAME&myip=IPV4

dynDNS.it accepts only public IPs. Private IPs like 192.168.x.x or 10.x.x.x are not assigned to hostnames.

Embed authentication with user and password

You can pass username and password as query string parameters without using an ‘Authorization’ Header

    https://update.dyndns.it/nic/update?hostname=HOSTNAME&username=USERNAME&password=PASSWORD

Embed authentication with key

You can pass HOSTKEY as query string parameters without using an ‘Authorization’ Header

    https://update.dyndns.it/nic/update?hostname=HOSTNAME&key=HOSTKEY

Technical Notes

1. All interactions with the dynDNS.it update platform are made via HTTP/HTTPS protocol using exclusively the GET method.
2. The dynDNS.it server is available at the address: update.dyndns.it, on port 80 for HTTP and on port 443 for the HTTPS.
3. Parameters are sent to the dynDNS.it update platform as name/value pairs as part of the HTTP query string. Please note that all parameters are optional while only the hostname is mandatory.
4. Authentication is required for all requests. dynDNS.it platform accepts different authentications method to update hostnames. (HTTP basic auth or username and password as parameters)
5. The general authentication method uses Basic HTTP Authentication. This method, commonly used by browsers, requires a Header, containing user and password, encoded in base64. For more information consult https://en.wikipedia.org/wiki/Basic_access_authentication
6. An alternative authentication method requires the inclusion of USERNAME and PASSWORD parameters in the query string.
7. After every request, the client receives a RESPONSE from the dynDNS.it update platform in a one-word code followed by any additional information. The client reading the RESPONSE can understand if the update requested has been successful.
8. The updating script must send updates ONLY when the IP of the connection changes, otherwise it is considered abusive behavior. The IP of the connection can be checked by sending an unauthenticated GET to the https://checkip.dyndns.it endpoint.

RAW HTTP Request Example

The generic request to the dynDNS.it update platform, using Basic HTTP Authentication:

GET /nic/update?hostname=[MY-HOSTNAME] HTTP/1.1
Host: update.dyndns.it
Authorization: Basic [BASE64-ENCODED-USERNAME:PASSWORD-PAIR]
User-Agent: [DEVICE-MODEL-MAKE-VERSION]

Client structure example

A generic client should implement the following structure:

1. Get the current connection IP from http://checkip.dyndns.it
2. if the current IP is different from the locally saved IP
   • Send the update to update.dyndns.it
   • Save the current IP in local storage
3. Sleep 5 minutes
4. jump to 1