docs/http-api/index.rst

   1 Built-in Webserver and HTTP API
   2 ===============================
   3
   4 The PowerDNS Authoritative Server features a built-in built-in webserver that exposes a JSON/REST API.
   5 This API allows for controlling several functions, reading statistics and modifying zone content, metadata and DNSSEC key material.
   6
   7 Webserver
   8 ---------
   9
  10 To launch the internal webserver, add a :ref:`setting-webserver` to the configuration file.
  11 This will instruct PowerDNS to start a webserver on localhost at port 8081, without password protection.
  12 By default the webserver listens on localhost, meaning only local users (on the same host) will be able to access the webserver. Since the default ACL before 4.1.0 allows access from everywhere if :ref:`setting-webserver-address` is set to a different value, we strongly advise the use of a password protection.
  13 The webserver lists a lot of potentially sensitive information about the PowerDNS process, including frequent queries, frequently failing queries, lists of remote hosts sending queries, hosts sending corrupt queries etc.
  14 The webserver does not allow remote management of the daemon, but allows control over the size of the queries and response rings that may be used to monitor activities.
  15 The following webserver related configuration items are available:
  16
  17 * :ref:`setting-webserver`: If set to anything but 'no', a webserver is launched.
  18 * :ref:`setting-webserver-address`: Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the physical IP address of your nameserver.
  19 * :ref:`setting-webserver-password`: If set, viewers will have to enter this plaintext password in order to gain access to the statistics, in addition to entering the configured API key on the index page.
  20 * :ref:`setting-webserver-port`: Port to bind the webserver to.
  21 * :ref:`setting-webserver-allow-from`: Netmasks that are allowed to connect to the webserver
  22
  23 Enabling the API
  24 ----------------
  25
  26 To enable the API, the webserver and the HTTP API need to be enabled.
  27 Add these lines to the ``pdns.conf``::
  28
  29   api=yes
  30   api-key=changeme
  31
  32 .. versionchanged:: 4.1.0
  33
  34   Setting :ref:`setting-api` also implicitly enables the webserver.
  35
  36 And restart, the following examples should start working::
  37
  38   curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost | jq .
  39   curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost/zones | jq .
  40
  41 Working with the API
  42 --------------------
  43
  44 This chapter describes the PowerDNS Authoritative API.
  45 When creating an API wrapper (for instance when fronting multiple API's), it is recommended to stick to this API specification.
  46 The API is described in the `OpenAPI format <https://www.openapis.org/>`_, also known as "Swagger", and this description is `available <https://raw.githubusercontent.com/PowerDNS/pdns/master/docs/http-api/swagger/authoritative-api-swagger.yaml>`_.
  47
  48 Authentication
  49 ~~~~~~~~~~~~~~
  50
  51 The PowerDNS daemons accept a static API Key, configured with the :ref:`setting-api-key` option, which has to be sent in the ``X-API-Key`` header.
  52
  53 Errors
  54 ~~~~~~
  55
  56 Response code ``4xx`` or ``5xx``, depending on the situation.
  57
  58 -  Invalid JSON body from client: ``400 Bad Request``
  59 -  Input validation failed: ``422 Unprocessable Entity``
  60 -  JSON body from client not a hash: ``400 Bad Request``
  61
  62 Error responses have a JSON body of this format:
  63
  64 .. code-block:: json
  65
  66     {
  67       "error": "short error message",
  68       "errors": [
  69         {  },
  70       ]
  71     }
  72
  73 Where ``errors`` is optional, and the contents are error-specific.
  74
  75 Data format
  76 ~~~~~~~~~~~
  77
  78 The API accepts and emits :rfc:`JSON <7159>`.
  79 The ``Accept:`` header determines the output format.
  80 An unknown value or ``*/*`` will cause a ``400 Bad Request``.
  81
  82 All text is UTF-8 and HTTP headers will reflect this.
  83
  84 Data types:
  85
  86 -  empty fields: ``null`` but present
  87 -  Regex: implementation defined
  88 -  Dates: ISO 8601
  89
  90 Endpoints and Objects in the API
  91 --------------------------------
  92
  93 The API has the basepath ``/api/v1`` and all URLs in this documentation are relative to this basepath.
  94
  95 The API exposes several endpoints and objects:
  96
  97 .. toctree::
  98   :maxdepth: 1
  99
 100   server
 101   zone
 102   cryptokey
 103   metadata
 104   search
 105   statistics