How to use the HTTP API

Simple DNS Plus can be prompted to perform different actions through HTTP - either directly from a browser, or any other program that can communicate through HTTP.

This functionality is not intended as a direct user interface, but rather a way to communicate with Simple DNS Plus from other applications over the network (for example, ASP pages running on IIS, PHP pages on Apache, etc.).

By default, Simple DNS Plus listens for HTTP requests on IP address 127.0.0.1 port 8053.

With this default configuration, you can open the HTTP API "home page" in your browser using http://127.0.0.1:8053

There you will find a link to the HTTP API specification file (Swagger / OpenAPI format) and a local copy of Swagger UI that you can use to explore and test the HTTP API.

Please note that only the same computer can connect to IP 127.0.0.1, so if you need to access this from another computer, you will need to configure Simple DNS Plus to listen on a different IP address.

You can change these setting in the Options dialog / HTTP API section.

For backwards compatibility, the HTTP API accepts both GET and POST requests for all the functions, and it accepts parameters either as URL query parameters or as HTML form parameters (URL encoded in the request body in content-type "x-www-form-urlencoded" requests) - or any combination of the two.

However we recommend that you use POST for any function that alerts the server state in any way, and use GET for the rest.

And for consistency, we recommend that you specify all parameters as part of the URL query.

For the "updatezone", "updateconfig", and "updatepluginconfig" functions, the API also accepts content-type "text/..." POST requests where the request body is considered the "data" parameter and all others parameters are specified in the URL query (recommended).

The response will either be a document (text, XML, or HTML depending on the parameters of the request) containing the result, an error 404 for unrecognized commands, or error 406 for requests that could no be performed.

The request document/path name must be one of the commands described below.

For example, to list the contents of the zone file for example.com, you could use the following (with GET):

http://127.0.0.1:8053/getzone?zone=example.com

Functions:

  • status
    Returns server status and request counters.
    Optionally include the field "format" with the value "text" (the default), "html", or "xml".

  • clearcache
    Clears the DNS cache.
    Same as selecting "Clear Cache" from the main window / File menu.

  • zonelist
    Returns a list of all zones on the server.
    Optionally specify a numeric zone group ID in the field "zonegroup" to limit the list to a single zone group.
    Optionally specify the list format in the field "format" (either "xml" or "text").

  • getzone
    Returns the text of a zone's zone file.
    Specify the zone name in the field "zone".

  • zoneversions
    Returns a list of stored versions of a zone (XML format).
    Specify the zone name in the field "zone".

  • getzoneversion
    Returns the zone file text for a specific version of a zone.
    Specify the zone name in the field "zone".
    Specify the zone version serial# in the field "serial".

  • removezone
    Removes an existing zone from the server.
    Specify the zone name in the field "zone".

  • updatehost
    Updates, creates, or deletes an A-record or AAAA-record (host address).
    A parent zone must already exist for the host name.
    Specify the host name in the field "host".
    Specify an IP address (IPv4 or IPv6) in the field "data" (if no data is specified, the record is deleted).
    Optionally specify a comment for the host record in the field "comment".

  • updatezone
    Updates or creates a new zone on the server.
    Specify the zone name in the field "zone".
    Specify the zone data in the field "data" (formatted as a standard zone file).
    For secondary zones, specify the primary server IP address in the field "masterip".
    Optionally specify a numeric ID in the field "zonegroup" matching a group ID in the "_zonegroups.xml" file.
    Make sure to increment the SOA-record serial number when using this function.

  • addrecord, updaterecord, removerecord
    Adds, updates, or removes a DNS record.
    Specify the zone name in the field "zone".
    Specify the record name in the field "name" using zone file format (@ = zone name, etc.)
    Specify the record type in the field "type" (for example: 'A' or 'MX')
    Specify the record data in the field "data" using zone file format (optional for removerecord)
    Optionally specify the record TTL in the field "ttl" in seconds.
    Optionally specify a comment for the record in the field "comment".

  • getconfig
    Returns the Simple DNS Plus configuration (Options dialog settings) in XML format.
    Note: The format of the configuration XML is not documented and is subject to change from version to version.

  • updateconfig
    Updates the Simple DNS Plus configuration (Options dialog settings).
    Specify the configuration XML in the field "data".
    To update individual settings, first use the "getconfig" function to retrieve the current configuration XML, update this, and then submit it back to the server using this function.
    Note: The format of the configuration XML is not documented and is subject to change from version to version.

  • zonegrouplist
    Returns a list of zone groups on the server (from the DNS Records window).
    Optionally specify the list format in the field "format" (either "xml" or "text").

  • addzonegroup
    Adds a new zone group and returns the numeric ID of the new zone group.
    Specify the name of the new zone group in the field "name".

  • renamezonegroup
    Renames an existing zone group.
    Specify the numeric ID of the zone group to rename in the field "id".
    Specify the new zone group name in the field "name".

  • removezonegroup
    Removes a zone group and all zones in it.
    Specify the numeric ID of the zone group to remove in the field "id".\

  • suspendzone, resumezone
    Suspends or resumes a zones.
    Specify the name of the zone to suspend/resume in the field "zone".

  • zonestatus
    Returns the current status of a zone (XML format).
    Specify the name of the zone in the field "zone".

  • pluginstate
    Returns state information about a running plug-in instance (result of SaveState method).
    The format and content of the returned data depends on the plug-in. Not all plug-ins return state data.
    Either specify the plug-in instance display name in the field "name" or the instance ID (a GUID) in the field "id".

  • getpluginconfig
    Returns configuration data for a plug-in instance.
    The format and content of the returned data depends on the plug-in.
    Either specify the plug-in instance display name in the field "name" or the instance ID (a GUID) in the field "id".

  • updatepluginconfig
    Updates a plug-in instance configuration.
    The expected format and content of the configuration data depends on the plug-in.
    Either specify the plug-in instance display name in the field "name" or the instance ID (a GUID) in the field "id".
    Specify the configuration data in the field "data".

Connect