# ones.
#extensions = []
#extensions = ['redjack.sphinx.lua', 'sphinxcontrib.httpdomain', 'sphinxjsondomain']
-extensions = ['sphinxcontrib.httpdomain', 'sphinxjsondomain',
+extensions = ['sphinxcontrib.openapi',
'sphinxcontrib.fulltoc', 'changelog']
# Add any paths that contain templates here, relative to this directory.
'.venv',
'security-advisories/security-policy.rst',
'common/secpoll.rst',
- 'common/api/zone.rst']
+ 'common/api/*']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
--- /dev/null
+Cryptokeys
+==========
+.. versionadded:: 4.1.0
+
+Allows for modifying DNSSEC key material via the API.
+
+Endpoints
+---------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers/{server_id}/zones/{zone_id}/cryptokeys /servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: Cryptokey
+++ /dev/null
-Cryptokeys
-==========
-
-CryptoKey
----------
-
-.. json:object:: CryptoKey
-
- Represents a DNSSEC crypto key
-
- :param string type: "Cryptokey"
- :param int id: The internal identifier, read only
- :param string keytype: One of the following: ``ksk``, ``zsk``, ``csk``
- :param bool active: Whether or not the key is in active use
- :param string dnskey: The DNSKEY record for this key
- :param [string] ds: An array of DS records for this key
- :param string privatekey: The private key in ISC format
- :param string algorithm: The key's algorithm
- :param int bit: The bitsize of this key
+++ /dev/null
-CryptoKeys endpoint
-===================
-
-.. versionadded:: 4.1.0
-
-These endpoints allow for the manipulation of DNSSEC crypto material.
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/cryptokeys
-
- Get all :json:object:`CryptoKeys <CryptoKey>` for a zone, except the privatekey
-
- :param server_id: The name of the server
- :param zone_id: The id value of the :json:object:`Zone`
-
-.. http:post:: /api/v1/servers/:server_id/zones/:zone_id/cryptokeys
-
- This method adds a new key to a zone, POST data should be a :json:object:`CryptoKey`.
- But not all fields needs to be present:
-
- The key can either be generated or imported by supplying the ``privatekey`` parameter.
-
- if ``privatekey``, ``bits`` and ``algorithm`` are null, a key will be generated based
- on the :ref:`setting-default-ksk-algorithm` and :ref:`setting-default-ksk-size`
- settings for a KSK and the :ref:`setting-default-zsk-algorithm` and :ref:`setting-default-zsk-size`
- options for a ZSK.
-
- :param server_id: The name of the server
- :param zone_id: The id value of the :json:object:`Zone`
- :statuscode 201: Everything was fine, returns all public data as a :json:object:`CryptoKey`.
- :statuscode 422: Returned when something is wrong with the content of the request.
- Contains an error message
- :resjson string error: Has the error message
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_name/cryptokeys/:cryptokey_id
-
- Returns all data about the :json:object:`CryptoKey`, including the ``privatekey``.
-
- :param string server_id: The name of the server
- :param string zone_id: The id value of the :json:object:`Zone`
- :param string cryptokey_id: The id value of the :json:object:`CryptoKey`
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_name/cryptokeys/:cryptokey_id
-
- This method changes a key from ``zone_name`` specified by ``cryptokey_id``.
- At this time, only changing the ``active`` parameter is supported.
-
- :param string server_id: The name of the server
- :param string zone_id: The id value of the :json:object:`Zone`
- :param string cryptokey_id: The id value of the :json:object:`CryptoKey`
- :reqjson bool active: The new 'active' status of the key
- :statuscode 204: Everything was fine, the key with ``cryptokey_id`` is de/activated.
- :statuscode 422: Returned when something is wrong with the content of the request.
- Contains an error message
- :resjson string error: Has the error message
-
-.. http:delete:: /api/v1/servers/:server_id/zones/:zone_name/cryptokeys/:cryptokey_id
-
- This method deletes a key from ``zone_name`` specified by ``cryptokey_id``.
-
- :param string server_id: The name of the server
- :param string zone_id: The id value of the :json:object:`Zone`
- :param string cryptokey_id: The id value of the :json:object:`CryptoKey`
- :statuscode 200: Everything was fine, the key with ``cryptokey_id`` is gone
- :statuscode 422: Returned when the key could not be removed.
- Contains an error message
- :resjson string error: Has the error message
+++ /dev/null
-Data Search Endpoint
-====================
-
-.. http:get:: /api/v1/servers/:server_id/search-data?q=:search_term&max=:max_results
-
- Search the data inside PowerDNS for ``search_term`` and return at most
- ``max_results``. This includes zones, records and comments. The ``*``
- character can be used in ``search_term`` as a wildcard character and the
- ``?`` character can be used as a wildcard for a single character.
-
- :param server_id: The name of the server
- :query string search_term: The term to search for
- :query int max_results: Maximum number of entries to return
-
- Response body is an array of one or more of the following objects:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- [
- {
- "name": "example.com.",
- "object_type": "zone",
- "zone_id": "example.com."
- }
- ]
-
-
- For a record:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- [
- {
- "content": "192.0.2.1",
- "disabled": false,
- "name": "www.example.com",
- "object_type": "record",
- "ttl": 1200,
- "type": "A",
- "zone": "example.com.",
- "zone_id": "example.com."
- }
- ]
-
- For a comment:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- [
- {
- "object_type": "comment",
- "name": "www.example.com",
- "content": "An awesome comment",
- "zone": "example.com.",
- "zone_id": "example.com."
- }
- ]
+++ /dev/null
-Zone Metadata endpoints
-=======================
-
-.. versionadded:: 4.1.0
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/metadata
-
- Get all the :json:object:`MetaData` associated with the zone.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
-.. http:post:: /api/v1/servers/:server_id/zones/:zone_id/metadata
-
- Creates a set of metadata entries of given kind for the zone.
- Existing metadata entries for the zone with the same kind are not overwritten.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_name/metadata/:metadata_kind
-
- Get the content of a single kind of :doc:`domain metadata <../domainmetadata>` as a list of :json:object:`MetaData` objects.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
- :param metadata_kind: The name of the metadata to retrieve
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_name/metadata/:metadata_kind
-
- Modify the content of a single kind of :doc:`domain metadata <../domainmetadata>`.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
- :param metadata_kind: The name of the metadata to edit
- :reqjson MetaData data: The list of :json:object:`MetaData` to set.
-
-.. http:delete:: /api/v1/servers/:server_id/zones/:zone_name/metadata/:metadata_kind
-
- Delete all items of a single kind of :doc:`domain metadata <../domainmetadata>`.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
- :param metadata_kind: The name of the metadata to delete
+++ /dev/null
-Zones endpoint
-==============
-.. http:get:: /api/v1/servers/:server_id/zones
-
- Get all zones from the server.
-
- :param server_id: The name of the server
-
-.. http:post:: /api/v1/servers/:server_id/zones
-
- Creates a new domain, returns the :json:object:`Zone` on creation.
-
- :param server_id: The name of the server
- :query rrsets: "true" (default) or "false", whether to include the "rrsets" in the response :json:object:`Zone` object.
- :statuscode 201: The zone was successfully created
-
- A :json:object:`Zone` MUST be sent in the request body.
-
- - ``dnssec``, ``nsec3narrow``, ``presigned``, ``nsec3param``, ``api_rectify``, ``active-keys`` are OPTIONAL.
- - ``dnssec``, ``nsec3narrow``, ``presigned``, ``api_rectify`` default to ``false``.
-
- The server MUST create a SOA record.
- The created SOA record SHOULD have serial set to the value given as ``serial`` (or 0 if missing), use the nameserver name, email, TTL values as specified in the PowerDNS configuration (``default-soa-name``, ``default-soa-mail``, etc).
- These default values can be overridden by supplying a custom SOA record in the records list.
- If ``soa_edit_api`` is set, the SOA record is edited according to the SOA-EDIT-API rules before storing it (also applies to custom SOA records).
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_id
-
- Returns zone information.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
- :query rrsets: "true" (default) or "false", whether to include the "rrsets" in the response :json:object:`Zone` object.
-
-.. http:delete:: /api/v1/servers/:server_id/zones/:zone_id
-
- Deletes this zone, all attached metadata and rrsets.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
-.. http:patch:: /api/v1/servers/:server_id/zones/:zone_id
-
- Modifies present RRsets and comments. Returns ``204 No Content`` on success.
-
- The new and old zone serials will be returned in `X-PDNS-New-Serial` and `X-PDNS-Old-Serial` headers (auth 4.1+).
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
- Example client body for PATCH:
-
- .. code-block:: json
-
- { "rrsets":
- [
- {
- "name": "www.example.com.",
- "type": "A",
- "ttl": 3600,
- "changetype": "REPLACE",
- "records":
- [
- {
- "content": "192.0.2.15",
- "disabled": false,
- "set-ptr": false
- }
- ],
- }
- ]
- }
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_id
-
- Modifies basic zone data (metadata).
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
- Allowed fields in client body: all except ``id``, ``url`` and ``name``.
- Returns ``204 No Content`` on success.
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_id/notify
-
- Send a DNS NOTIFY to all slaves.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
- Fails when zone kind is not ``Master`` or ``Slave``, or ``master`` and ``slave`` are disabled in the configuration.
- Only works for ``Slave`` if renotify is on.
-
- Clients MUST NOT send a body.
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_id/axfr-retrieve
-
- Retrieves the zone from the master.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
- Fails when zone kind is not ``Slave``, or ``slave`` is disabled in PowerDNS configuration.
-
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/export
-
- Returns the zone in AXFR format.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
-.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/check
-
- Verify zone contents/configuration.
-
- Return format:
-
- .. code-block: json
-
- {
- "zone": "<zone_name>",
- "errors": ["error message1"],
- "warnings": ["warning message1"]
- }
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
-.. http:put:: /api/v1/servers/:server_id/zones/:zone_id/rectify
-
- Rectify the zone data. This does not take into account the :ref:`metadata-api-rectify` metadata.
-
- :param server_id: The name of the server
- :param zone_id: The id number of the :json:object:`Zone`
-
- Fails on slave zones and zones that do not have DNSSEC.
===============================
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.
+This API allows for controlling several functions, reading statistics and modifying zone content, metadata and DNSSEC key material.
Webserver
---------
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:
+
+.. code-block:: json
+
+ {
+ "error": "short error message",
+ "errors": [
+ { },
+ ]
+ }
+
+Where ``errors`` is optional, and the contents are error-specific.
+
+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
+ search
+ statistics
--- /dev/null
+Metadata
+========
+
+Endpoints
+---------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers/{server_id}/zones/{zone_id}/metadata /servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: Metadata
--- /dev/null
+Searching
+=========
+
+The API allows searching for data in :json:object:`Zone`\ s, :json:object:`Comment`\ s and :json:object:`RRSet`\ s.
+
+Endpoints
+---------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers/{server_id}/search-data /servers/{server_id}/search-log
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: SearchResult
--- /dev/null
+Servers
+=======
+
+The server endpoint is the 'basis' for all other API operations.
+In the PowerDNS Authoritative Server, the ``server_id`` is always ``localhost``.
+However, the API is written in a way that a proxy could be in front of many servers, each with their own ``server_id``.
+
+Endpoints
+---------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers /servers/{server_id}
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: Server
--- /dev/null
+Statistics
+==========
+
+Endpoints
+---------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers/{server_id}/statistics
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: StatisticItem
+
definitions:
Server:
+ title: Server
properties:
type:
type: string
$ref: '#/definitions/Server'
Zone:
+ title: Zone
+ description: This represents an authoritative DNS Zone.
properties:
id:
type: string
$ref: '#/definitions/Zone'
RRSet:
+ title: RRSet
+ description: This represents a Resource Record Set (all records with the same name and type).
required:
- name
- type
$ref: '#/definitions/Comment'
Record:
+ title: Record
+ description: The RREntry object represents a single record.
required:
- content
- disabled # PatchZone endpoint complains if this is missing
description: 'If set to true, the server will find the matching reverse zone and create a PTR there. Existing PTR records are replaced. If no matching reverse Zone, an error is thrown. Only valid in client bodies, only valid for A and AAAA types. Not returned by the server.'
Comment:
+ title: Comment
+ description: A comment about an RRSet.
properties:
content:
type: string
description: 'Timestamp of the last change to the comment'
ConfigSetting:
+ title: ConfigSetting
properties:
name:
type: string
description: 'The value of setting name'
StatisticItem:
+ title: StatisticItem
properties:
name:
type: string
description: 'The value of item'
SearchResultZone:
+ title: SearchResultZone
properties:
name:
type: string
type: string
SearchResultRecord:
+ title: SearchResultRecord
properties:
content:
type: string
type: integer
SearchResultComment:
+ title: SearchResultComment
properties:
content:
type: string
# Since we can't do 'anyOf' at the moment, we create a 'superset object'
SearchResult:
+ title: SearchResult
properties:
content:
type: string
$ref: '#/definitions/SearchResult'
Metadata:
+ title: Metadata
+ description: Represents zone metadata
properties:
kind:
type: string
description: 'Array with all values for this metadata kind.'
Cryptokey:
+ title: Cryptokey
+ description: 'Describes a DNSSEC cryptographic key'
properties:
type:
type: string
Zones
=====
-Zone
-----
+Manipulating zones is the primary use of the API.
+
+Zone Endpoints
+--------------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :paths: /servers/{server_id}/zones /servers/{server_id}/zones/{zone_id} /servers/{server_id}/zones/{zone_id}/axfr-retrieve /servers/{server_id}/zones/{zone_id}/notify /servers/{server_id}/zones/{zone_id}/export /servers/{server_id}/zones/{zone_id}/check /servers/{server_id}/zones/{zone_id}/rectify
+
+Objects
+-------
A Zone object represents an authoritative DNS Zone.
Comments are per-RRset.
-.. json:object:: Zone
-
- Represents a configured zone in the PowerDNS server.
-
- :property string id: Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs.
- :property string name: Name of the zone (e.g. "example.com.") MUST have a trailing dot
- :property string type: Set to "Zone"
- :property string url: API endpoint for this zone
- :property string kind: Zone kind, one of "Native", "Master", "Slave"
- :property [RRSet] rrsets: RRSets in this zone
- :property integer serial: The SOA serial number
- :property integer notified_serial: The SOA serial notifications have been sent out for
- :property [str] masters: List of IP addresses configured as a master for this zone ("Slave" type zones only)
- :property bool dnssec: Whether or not this zone is DNSSEC signed (inferred from presigned being true XOR presence of at least one cryptokey with active being true)
- :property string nsec3param: The NSEC3PARAM record
- :property bool nsec3narrow: Whether or not the zone uses NSEC3 narrow
- :property bool presigned: Whether or not the zone is pre-signed
- :property string soa_edit: The :ref:`metadata-soa-edit` metadata item
- :property string soa_edit_api: The :ref:`metadata-soa-edit-api` metadata item
- :property bool api_rectify: Whether or not the zone will be rectified on data changes via the API
- :property string zone: MAY contain a BIND-style zone file when creating a zone
- :property str account: MAY be set. Its value is defined by local policy
- :property [str] nameservers: MAY be sent in client bodies during creation, and MUST NOT be sent by the server. Simple list of strings of nameserver names, including the trailing dot. Not required for slave zones.
+.. openapi:: swagger/authoritative-api-swagger.yaml
+ :definitions: Zone RRSet Record Comment
.. note::
When creating a slave zone, it is recommended to not set any of
``nameservers``, ``rrsets`` or ``zone``.
-
-.. include:: ../common/api/zone.rst
+++ /dev/null
-Zone Metadata
-=============
-
-.. versionadded:: 4.1.0.
-
-.. json:object:: Metadata
-
- Represents zone metadata :doc:`../domainmetadata`
-
- :property string kind: Name of the metadata
- :property [string] metadata: Array with all values for this metadata kind.
-
- Clients MUST NOT modify ``NSEC3PARAM``, ``NSEC3NARROW``, ``PRESIGNED`` and ``LUA-AXFR-SCRIPT`` through this interface.
- The server rejects updates to these metadata.
- Modifications to custom metadata kinds starting with ``X-`` is allowed as well.
Sphinx>=1.5.0
+git+https://github.com/pieterlexis/sphinxcontrib-openapi@use-jsondomain
git+https://github.com/pieterlexis/sphinx-jsondomain@no-type-links
git+https://github.com/pieterlexis/sphinx-changelog@render-tags
-sphinxcontrib-httpdomain
sphinxcontrib-fulltoc
guzzle_sphinx_theme
Renamed from ``default-ksk-algorithms``. No longer supports multiple algorithm names.
The algorithm that should be used for the KSK when running
-:doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/endpoint-zones>`
+:doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/cryptokey>`
to enable DNSSEC. Must be one of:
* rsamd5
Renamed from ``default-zsk-algorithms``. Does no longer support multiple algorithm names.
The algorithm that should be used for the ZSK when running
-:doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/endpoint-zones>`
+:doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/cryptokey>`
to enable DNSSEC. Must be one of:
* rsamd5
projects / pdns / commitdiff