Built-in Webserver and HTTP API
===============================
-The PowerDNS Authoritative Server features a built-in built-in webserver that exposes a JSON/REST API.
-This API allows for controlling several functions and reading statistics.
+The PowerDNS Authoritative Server features a built-in webserver that exposes a JSON/REST API.
+This API allows for controlling several functions, reading statistics and modifying zone content, metadata and DNSSEC key material.
Webserver
---------
* :ref:`setting-webserver`: If set to anything but 'no', a webserver is launched.
* :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.
-* :ref:`setting-webserver-password`: If set, viewers will have to enter this plaintext password in order to gain access to the statistics.
+* :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.
* :ref:`setting-webserver-port`: Port to bind the webserver to.
* :ref:`setting-webserver-allow-from`: Netmasks that are allowed to connect to the webserver
+* :ref:`setting-webserver-max-bodysize`: Maximum request/response body size in megabytes
Enabling the API
----------------
To enable the API, the webserver and the HTTP API need to be enabled.
Add these lines to the ``pdns.conf``::
- api=yes
- api-key=changeme
- webserver=yes
- webserver-port=8081
+ api=yes
+ api-key=changeme
-The API endpoints run off of the same webserver, but the :ref:`setting-api` is required to enable API access. Setting :ref:`setting-api` also implicitly enables the webserver v4.1.x onwards.
+.. versionchanged:: 4.1.0
+
+ Setting :ref:`setting-api` also implicitly enables the webserver.
And restart, the following examples should start working::
- curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost | jq .
- curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost/zones | jq .
+ curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost | jq .
+ curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost/zones | jq .
-JSON Objects
-------------
+Working with the API
+--------------------
-The following documents describe the JSON objects available in the API:
+This chapter describes the PowerDNS Authoritative API.
+When creating an API wrapper (for instance when fronting multiple API's), it is recommended to stick to this API specification.
+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>`_.
-.. toctree::
- :maxdepth: 1
+Authentication
+~~~~~~~~~~~~~~
+
+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.
+
+Errors
+~~~~~~
+
+Response code ``4xx`` or ``5xx``, depending on the situation.
+
+- Invalid JSON body from client: ``400 Bad Request``
+- Input validation failed: ``422 Unprocessable Entity``
+- JSON body from client not a hash: ``400 Bad Request``
+
+Error responses have a JSON body of this format:
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: Error
+
+Data format
+~~~~~~~~~~~
+
+The API accepts and emits :rfc:`JSON <7159>`.
+The ``Accept:`` header determines the output format.
+An unknown value or ``*/*`` will cause a ``400 Bad Request``.
+
+All text is UTF-8 and HTTP headers will reflect this.
+
+Data types:
+
+- empty fields: ``null`` but present
+- Regex: implementation defined
+- Dates: ISO 8601
- ../common/api/dataformat
- ../common/api/server
- zone
- ../common/api/configsetting
- ../common/api/statisticitem
- cryptokeyitem
- zonemetadata
+Endpoints and Objects in the API
+--------------------------------
-URL Endpoints
--------------
+The API has the basepath ``/api/v1`` and all URLs in this documentation are relative to this basepath.
-All API endpoints for the PowerDNS Recursor are documented here:
+The API exposes several endpoints and objects:
.. toctree::
:maxdepth: 1
- ../common/api/endpoint-api
- ../common/api/endpoint-servers
- ../common/api/endpoint-servers-config
- ../common/api/endpoint-statistics
- ../common/api/endpoint-logging
- endpoint-search
- endpoint-zones
- endpoint-zone-metadata
- endpoint-cryptokeys
+ server
+ zone
+ cryptokey
+ metadata
+ tsigkey
+ search
+ statistics
+ cache
projects / thirdparty / pdns.git / blobdiff