doc: Add missing Zone properties and SOA-EDIT-API

Closes #3895
Closes #4129

diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst
index c8bc41c017df479b053859c1047a360c697c16b1..686b23bf4c97e4d413750bc6dd6afbd870aff836 100644 (file)
--- a/docs/dnsupdate.rst
+++ b/docs/dnsupdate.rst
@@ -170,6 +170,8 @@ verification.
     5
     sql> insert into domainmetadata(domain_id, kind, content) values(5, ‘NOTIFY-DNSUPDATE’,’1’);
 
+.. _metadata-soa-edit-dnsupdate:
+
 SOA-EDIT-DNSUPDATE
 ~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/domainmetadata.rst b/docs/domainmetadata.rst
index 97f383e5ede753bd33c43b147e29607b8a73b287..c58917ebc648927d79d780a9d8fcb30b4a832d5f 100644 (file)
--- a/docs/domainmetadata.rst
+++ b/docs/domainmetadata.rst
@@ -169,6 +169,19 @@ fresh RRSIGs. See the :ref:`DNSSEC
 documentation <soa-edit-ensure-signature-freshness-on-slaves>`
 for more information.
 
+.. _metadata-soa-edit-api:
+
+SOA-EDIT-API
+------------
+
+On changes to the contents of a zone made through the :doc:`API <http-api/index>`,
+the SOA record will be edited according to the SOA-EDIT-API rules. These rules
+are the same as the :ref:`SOA-EDIT-DNSUPDATE <dnsupdate-soa-serial-updates>` rules.
+If not set during zone creation, a SOA-EDIT-API metadata record is created and set to ``DEFAULT``.
+If this record is removed from the backend, the default behaviour is to not do any SOA editing based on this setting.
+This is different from setting ``DEFAULT``.
+
+
 TSIG-ALLOW-AXFR
 ---------------
 

diff --git a/docs/http-api/endpoint-zones.rst b/docs/http-api/endpoint-zones.rst
index 2a1c369503ed06a908bb72b3f6e237da23abefc3..4e82e1f0f3a103b671f8952aaca60d9a5d6c3ad7 100644 (file)
--- a/docs/http-api/endpoint-zones.rst
+++ b/docs/http-api/endpoint-zones.rst
@@ -12,6 +12,8 @@ Zones endpoint
 
   :param server_id: The name of the server
 
+  A :json:object:`Zone` MUST be sent in the request body.
+
   -  ``dnssec``, ``nsec3narrow``, ``presigned``, ``nsec3param``, ``active-keys`` are OPTIONAL.
   -  ``dnssec``, ``nsec3narrow``, ``presigned`` default to ``false``.
 

diff --git a/docs/http-api/zone-properties.rst b/docs/http-api/zone-properties.rst
index 64806bd1880e02ef2e2b2c6e45b4eed025965cb2..dda636e0d1585733d9fed1cbcdc2f80f3e7744ac 100644 (file)
--- a/docs/http-api/zone-properties.rst
+++ b/docs/http-api/zone-properties.rst
@@ -1,3 +1,4 @@
+  
   :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)
@@ -5,58 +6,37 @@
   :property string nsec3param: The NSEC3PARAM record (not implemented)
   :property bool nsec3narrow: Whether or not the zone uses NSEC3 narrow (not implemented)
   :property bool presigned: Whether or not the zone is pre-signed (not implemented)
-  :property string soa_edit: The SOA-EDIT metadata item. MAY be set to change the ``SOA-EDIT`` zone setting.
-  :property string soa_edit_api: The SOA-EDIT-API metadata item
+  :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 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.
 
+.. note::
 
+  Switching ``dnssec`` to ``true`` (from ``false``) sets up DNSSEC signing
+  based on the other flags, this includes running the equivalent of
+  ``secure-zone`` and ``rectify-zone``. This also applies to newly created
+  zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to
+  the zone or cryptokeys.
 
-Switching ``dnssec`` to ``true`` (from ``false``) sets up DNSSEC signing
-based on the other flags, this includes running the equivalent of
-``secure-zone`` and ``rectify-zone``. This also applies to newly created
-zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to
-the zone or cryptokeys. .
+  ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are not yet implemented.
 
-**TODO**: ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are
-not yet implemented.
+.. note::
 
--  ``soa_edit_api`` MAY be set. If it is set, on changes to the contents
-   of a zone made through the API, the SOA record will be edited
-   according to the SOA-EDIT-API rules. (Which are the same as the
-   SOA-EDIT-DNSUPDATE rules.) If not set during zone creation, a
-   SOA-EDIT-API metadata record is created and set to ``DEFAULT``. (If
-   this record is removed from the backend, the default behaviour is to
-   not do any SOA editing based on this setting. This is different from
-   setting ``DEFAULT``).
-
--  ``account`` MAY be set. Its value is defined by local policy.
-
--  ``notified_serial``, ``serial`` MUST NOT be sent in client bodies.
-
--  ``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. Note: Before 4.0.0, names were
-   taken without the trailing dot. . Not
-   required for slave zones.
-
--  ``rrsets``: list of DNS records and comments in the zone.
-
-Please see the description for ``PATCH`` for details on the fields in
-``RRset``, ``Record`` and ``Comment``.
-
-Turning on DNSSEC with custom keys: just create the zone with ``dnssec``
-set to ``false``, and add keys using the cryptokeys REST interface. Have
-at least one of them ``active`` set to ``true``. **TODO**: not yet
-implemented.
+  ``notified_serial``, ``serial`` MUST NOT be sent in client bodies.
 
 Changes made through the Zones API will always yield valid zone data,
-and the zone will be properly "rectified" (**TODO**: not yet
-implemented). If changes are made through other means (e.g. direct
-database access), this is not guaranteed to be true and clients SHOULD
+and the zone will be properly "rectified". If changes are made through other means
+(e.g. direct database access), this is not guaranteed to be true and clients SHOULD
 trigger rectify.
 
+.. note::
+
+  Rectification is not yet implemented.
+
 Backends might implement additional features (by coincidence or not).
 These things are not supported through the API.
 
 When creating a slave zone, it is recommended to not set any of
-``nameservers``, ``records``.
-
+``nameservers``, ``records`` or ``zone``.