The ZoneControl API
===================
The ZoneControl frontend communicates with the ZoneControl server application
using the ZoneControl REST API. This API is the
`PowerDNS API <https://doc.powerdns.com/authoritative/http-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 </api/v1/servers/{server_id}/zones/{zone_id}/_names/{name}/_comments/{rrtype}>`
  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.

