The ZoneControl API

The ZoneControl frontend communicates with the ZoneControl server application using the ZoneControl REST API. This API is the PowerDNS API with some additional endpoints for ZoneControl object like comments, and history.

Apart from that, ZoneControl

ZoneControl Endpoints

GET /api/zonecontrol/info

Returns information for the frontend regarding enabled features of the server and some permissions for the user. This is used by the frontend to show or hide certain UI elements.

Response JSON Object:

  • username (str) – Username of the logged in user.

  • is_admin (bool) – User is a staff user.

  • can_add_zones (bool) – User can create zones on at least one server.

  • can_add_zone_kinds (list(str)) – The kinds of zones this user can create.

  • show_advanced_dnssec (bool) – Whether this user had Advanced DNSSEC permissions.

  • can_add_ptr (bool) – Whether automatic PTR creation is enabled.

  • can_queue_axfr_retrieve (bool) – Whether or not the user can queue AXFR retrievals.

  • can_queue_notify (bool) – Whether or not the user can queue NOTIFY messages.

  • dnssec_in_overview (bool) – Whether or not DNSSEC is shown in the zones overview.

  • dnssec_advanced_default_algorithm (bool) – The default algorithm in the Advanced DNSSEC view.

  • dnssec_advanced_algorithms (bool) – The algorithms shown in the Advanced DNSSEC view.

  • nsec3param_default (bool) – The default value for NSEC3.

POST /api/zonecontrol/login

This endpoint allows a login.

Form Parameters:

  • username – Username to log in.

  • password – Password for the user.

Status Codes:

On success, a JSON object is returned.

Response JSON Object:

  • success (bool) – Always true on a login.

ZoneControl Endpoints in the PowerDNS API

GET /api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype}

Retrieve the comments for a certain record.

Parameters:

  • server_id (str) – Name of the server

  • zone_id (str) – id (name) of the zone

  • name (str) – Name of the RRSet

  • rrtype (str) – RRType in textual format (e.g. A, AAAA, CNAME)

Returns a JSON object with one element data with contains an array of objects.

Response JSON Array of Objects:

  • server (str) – Name of the server this comment was made for.

  • zone (str) – Name of the zone this comment was made for.

  • name (str) – RRSet name.

  • type (str) – RRType.

  • timestamp (str) – Timestamp the comment was created.

  • user (str) – Username of the comment’s author.

  • comment (str) – The actual comment.

  • from-server (bool) – Whether or not the server was sent from the server, always true on a GET request.

POST /api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype}

Create a comment for a certain record. The request body must be a single JSON string with the comment. All database fields (user, timestamp etc.) will be filled by the server.

Parameters:

  • server_id (str) – Name of the server

  • zone_id (str) – id (name) of the zone

  • name (str) – Name of the RRSet

  • rrtype (str) – RRType in textual format (e.g. A, AAAA, CNAME)

Returns all comments as if the GET for the same URL was called.

DELETE /api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype}/_comment/{comment_id}

Delete the comment with id comment_id

Parameters:

  • server_id – Name of the server

  • zone_id – id (name) of the zone

  • name – Name of the RRSet

  • comment_id – id of the comment

GET /api/v1/servers/{server_id}/zones/{zone_id}/_history

Get all versions for the zone.

Parameters:

  • server_id – Name of the server

  • zone_id – id (name) of the zone

Returns a JSON object with one element data with contains an array of zone versions.

Response JSON Array of Objects:

  • id (int) – id of the ZoneVersion

  • serial (int) – SOA Serial of the zone

  • action (string) –

    The action of this version of the zone, one of

    create:

    Zone was created at this version

    delete:

    Zone was deleted at this version

    settings:

    Zone settings (e.g. kind) was changed

    metadata:

    Zone Metadata was changed

    dnssec_enable:

    DNSSEC was enabled

  • action_display (string) – The action as a user-readable string, can be null.

  • can_be_restored (bool) – Whether or not the zone can be rolled back to this version.

  • comment (string) – Comment made when the version was created.

  • timestamp (str) – Timestamp the version was created.

  • username (str) – Name of the user who created the version, can be null.

  • external (bool) – True if the version was not created through a change in ZoneControl.

GET /api/v1/servers/{server_id}/zones/{zone_id}/_history/diff/{version_2}
GET /api/v1/servers/{server_id}/zones/{zone_id}/_history/diff/{version_1}/{version_2}

Get a difference between zone versions.

Parameters:

  • server_id – Name of the server

  • zone_id – id (name) of the zone

  • version_1 – Version to compare to

  • version_2 – Diff to retrieve

POST /api/v1/servers/{server_id}/zones/{zone_id}/_history/restore/{version}

Restore a Zone to the provided version.

Parameters:

  • server_id – Name of the server

  • zone_id – id (name) of the zone

  • version – Version to restore to

When restoration succeeds, a HTTP 200 response is returned with the following JSON:

Response JSON Object:

  • success (bool) – Whether or not the restoration succeeded.

  • new_version_recorded (bool) – Whether or a new version was recorded.

  • new_version (int) – id of the new version that was recorded.

  • new_serial (int) – SOA serial of the zone after the restoration.

  • warning (str) – A warning if a failure occurred.

  • warning_details (str) – More warning information.

API Tokens

Users can be assigned API tokens from the administrative interface. This token can be used in HTTP requests to the ZoneControl server in the X-Api-Key header. This allows users to write their own applications that interact with the PowerDNS API while still keeping the Role permissions in place.