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 --------------------- .. http: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. :>json str username: Username of the logged in user. :>json bool is_admin: User is a staff user. :>json bool can_add_zones: User can create zones on at least one server. :>json list(str) can_add_zone_kinds: The kinds of zones this user can create. :>json bool show_advanced_dnssec: Whether this user had Advanced DNSSEC permissions. :>json bool can_add_ptr: Whether automatic PTR creation is enabled. :>json bool can_queue_axfr_retrieve: Whether or not the user can queue AXFR retrievals. :>json bool can_queue_notify: Whether or not the user can queue NOTIFY messages. :>json bool dnssec_in_overview: Whether or not DNSSEC is shown in the zones overview. :>json bool dnssec_advanced_default_algorithm: The default algorithm in the Advanced DNSSEC view. :>json bool dnssec_advanced_algorithms: The algorithms shown in the Advanced DNSSEC view. :>json bool nsec3param_default: The default value for NSEC3. .. http:post:: /api/zonecontrol/login This endpoint allows a login. :form username: Username to log in. :form password: Password for the user. :status 200: Login successful. :status 401: Login failed. On success, a JSON object is returned. :>json bool success: Always true on a login. ZoneControl Endpoints in the PowerDNS API ----------------------------------------- .. http:get:: /api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype} Retrieve the comments for a certain record. :param str server_id: Name of the server :param str zone_id: id (name) of the zone :param str name: Name of the RRSet :param str rrtype: RRType in textual format (e.g. A, AAAA, CNAME) Returns a JSON object with one element ``data`` with contains an array of objects. :>jsonarr str server: Name of the server this comment was made for. :>jsonarr str zone: Name of the zone this comment was made for. :>jsonarr str name: RRSet name. :>jsonarr str type: RRType. :>jsonarr str timestamp: Timestamp the comment was created. :>jsonarr str user: Username of the comment's author. :>jsonarr str comment: The actual comment. :>jsonarr bool from-server: Whether or not the server was sent from the server, always true on a GET request. .. http: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. :param str server_id: Name of the server :param str zone_id: id (name) of the zone :param str name: Name of the RRSet :param str rrtype: RRType in textual format (e.g. A, AAAA, CNAME) Returns all comments as if :http:get:`the GET for the same URL ` was called. .. http:delete:: /api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype}/_comment/{comment_id} Delete the comment with id ``comment_id`` :param server_id: Name of the server :param zone_id: id (name) of the zone :param name: Name of the RRSet :param comment_id: id of the comment .. http:get:: /api/v1/servers/{server_id}/zones/{zone_id}/_history Get all versions for the zone. :param server_id: Name of the server :param zone_id: id (name) of the zone Returns a JSON object with one element ``data`` with contains an array of zone versions. :>jsonarr int id: id of the ZoneVersion :>jsonarr int serial: SOA Serial of the zone :>jsonarr string action: 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 :>jsonarr string action_display: The action as a user-readable string, can be null. :>jsonarr bool can_be_restored: Whether or not the zone can be rolled back to this version. :>jsonarr string comment: Comment made when the version was created. :>jsonarr str timestamp: Timestamp the version was created. :>jsonarr str username: Name of the user who created the version, can be null. :>jsonarr bool external: True if the version was not created through a change in ZoneControl. .. http:get:: /api/v1/servers/{server_id}/zones/{zone_id}/_history/diff/{version_2} /api/v1/servers/{server_id}/zones/{zone_id}/_history/diff/{version_1}/{version_2} Get a difference between zone versions. :param server_id: Name of the server :param zone_id: id (name) of the zone :param version_1: Version to compare to :param version_2: Diff to retrieve .. http:post:: /api/v1/servers/{server_id}/zones/{zone_id}/_history/restore/{version} Restore a Zone to the provided version. :param server_id: Name of the server :param zone_id: id (name) of the zone :param version: Version to restore to When restoration succeeds, a HTTP 200 response is returned with the following JSON: :>json bool success: Whether or not the restoration succeeded. :>json bool new_version_recorded: Whether or a new version was recorded. :>json int new_version: id of the new version that was recorded. :>json int new_serial: SOA serial of the zone after the restoration. :>json str warning: A warning if a failure occurred. :>json str warning_details: 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.