Overview

Methodology

• All interaction with the IP update server are made via HTTP/HTTPS protocol using exclusively the GET method. HTTP IP update server is available on ports 80 and 8245 while the HTTPS API server is available on port 443. Port 8245 is highly recommended for HTTP based requests in order to avoid alterations to requests done by any HTTP based proxy server.
• Authentication is required for most queries/actions using 'Authorization' HTTP header. The Base 64 encoded string will contain a username:password combination. The username may be obtained from the control panel. The authentication credentials may also be sent across as URL querystring parameters.
• Parameters are passed to the IP update server as name/value pairs as part of HTTP querystring. Please note that some parameters are optional while others are mandatory.
• The RESPONSE from the IP update server is a one word return code followed by any additional information.
• Example HTTP Request:
  
  
  GET /nic/update?myip=198.144.117.32 HTTP/1.1
  Host: api.dynu.com
  Authorization: Basic [BASE64-ENCODED-USERNAME:PASSWORD-PAIR]
  User-Agent: [DEVICE-MODEL-MAKE-VERSION]
  

NOTE: Basic auth embedded in URL is NO LONGER supported by most browsers. Please refer to the following issue regarding Chrome:
https://code.google.com/p/chromium/issues/detail?id=123150

If the browser does not support basic auth embedded in URL , you can simply pass the USERNAME and PASSWORD parameters as part of querystring parameters to test the API. Please note that you may pass the MD5/SHA-256 hash of the password instead of the actual password for security reasons.

Requests

There are many types of requests which can be directed towards the IP update server. Some are informational in nature while others are action based. All requests without exception will be responded with a 'response code' indicating the validity of the request processed.

Primary IP Address Update

This action is used to update the primary IP address for the domain name. Either the username or hostname must be supplied.

Parameters:

PASSWORD  Required. The password may be supplied normally or as an MD5/SHA256 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

USERNAME  Optional. Providing the username and no hostnames will update the IP address for all hostnames in the user account that have not been assigned a location name.

LOCATION  Optional. Use 'location' parameter if you want to update IP address for a collection of hostnames including those created using subdomains. Please note that the 'username' and 'password' parameters are mandatory when using location. The 'hostname' parameter is ignored when 'location' parameter is used.

HOSTNAME  Optional. One or more comma-separated hostnames whose IP address requires update. If you wish to update the IP address of all hostnames in the account, use the 'username' parameter instead.

IP ADDRESS  Optional. IPv4 address to be used for update. This field is OPTIONAL. If IP addrss is not sent as part of the request, the API server will use the IP address from which the request originates. The special IP address 10.0.0.0 is replaced with the IP address from which the request originates and you may use it with routers which disallow empty IP address field. If you need to block the update of the IPv4 address, use myip=no as part of the update URL.

IPv6 ADDRESS  Optional. IPv6 address to be used for update. If you need to block the update of the IPv6 address, use myipv6=no as part of the update URL.

Alias/Subdomain IP Address Update

This action is used to update the IP address of an alias/subdomain for the domain name. Please make sure to add this alias/subdomain in the 'Aliases/Subdomains' section in the control panel for the domain name. If 'Wildcard' option is enabled in the control panel, virtually all aliases/subdomains point to the primary IP address by default.

Parameters:

PASSWORD  Required. The password may be supplied normally or as an MD5/SHA256 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

HOSTNAME  Required. A single hostname whose alias/subdomain requires IP address update.

ALIAS  Required. The alias/subdomain of hostname whose IP address requires update.

IP ADDRESS  Optional. IP address to be used for update. This field is OPTIONAL. If IP address is not sent as part of the request, the API server will use the IP address from which the request originates. The special IP address 10.0.0.0 is replaced with the IP address from which the request originates and you may use it with routers which disallow empty IP address field. If you need to block the update of the IPv4 address, use myip=no as part of the update URL.

IPv6 ADDRESS  Optional. IPv6 address to be used for update. If you need to block the update of the IPv6 address, use myipv6=no as part of the update URL.

Setting 'Signoff' status

This action is used when the server/router is going offline and would like to point the domain name to an offline message or offline URL. The offline action itself can be setup in the control panel.

Parameters:

PASSWORD  Required. The password may be supplied normally or as an MD5/SHA256 hash for security reasons. Be sure to take advantage of setting up a separate IP update password different from the account password.

HOSTNAME  Required. A single hostname whose IP address requires update.

Response Codes

When an API 'request' is made, the API server will respond with a 'response code'. The client software should use the response codes to communicate a friendly message back to the user. Please note that in cases where multiple 'requests' are sent using a single HTTP request(for example, updating IP address for multiple domain names), multiple 'response codes' will be returned separated by a break(CRLF). Please refer to each individual 'request' for appropriate 'response codes'. Below are some common 'response codes':

unknown  This response code is returned if an invalid 'request' is made to the API server. This 'response code' could be generated as a result of badly formatted parameters as well so parameters must be checked for validity by the client before they are passed along with the 'request'.

good  This response code means that the action has been processed successfully. Further details of the action may be included along with this 'response code'.

badauth  This response code is returned in case of a failed authentication for the 'request'. Please note that sending across an invalid parameter such as an unknown domain name can also result in this 'response code'. The client must advise the user to check all parameters including authentication parameters to resolve this problem.

servererror  This response code is returned in cases where an error was encountered on the server side. The client may send across the request again to have the 'request' processed successfully.

nochg  This response code is returned in cases where IP address was found to be unchanged on the server side.

notfqdn  This response code is returned in cases where the hostname is not a valid fully qualified hostname.

numhost  This response code is returned in cases where too many hostnames(more than 20) are specified for the update process.

abuse  This response code is returned in cases where update process has failed due to abusive behaviour.

nohost  This response code is returned in cases where hostname/username is not found in the system.

911  This response code is returned in cases where the update is temporarily halted due to scheduled maintenance. Client must respond by suspending update process for 10 minutes upon receiving this response code.

dnserr  This response code is returned in cases where there was an error on the server side. The client must respond by retrying the update process.

!donator  This response code is returned to indicate that this functionality is only available to members.

GnuDIP Support

Both TCP and HTTP based GnuDIP is fully supported. Routers supporting GnuDIP IP update as well as any GnuDIP based IP update clients may be used to make full use of this functionality.

IPv4 and IPv6 Servers

If you pass in the myip= and myipv6= parameter in the IP update URL, the below 3 server names work the same. All of them will update both the IPv4 and IPv6 addresses exactly like you send them.

However, if you do not pass in the myip= and myipv6= parameter and allow the IP address to be detected by our API servers, the api-ipv4.dynu.com server will detect the IPv4 address and the api-ipv6.dynu.com server will detect the IPv6 address. If you use api.dynu.com, either the IPv4 address or the IPv6 address will get detected depending on which address family is used by your device to communicate with our API.