Zones ===== 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}/rectify Objects ------- A Zone object represents an authoritative DNS Zone. A Resource Record Set (below as "RRset") are all records for a given name and type. Comments are per-RRset. .. openapi:: swagger/authoritative-api-swagger.yaml :definitions: Zone RRSet Record Comment .. 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`` (if ``api_rectify`` is set to ``true``). This also applies to newly created zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to the zone or cryptokeys. .. note:: ``notified_serial``, ``serial`` MUST NOT be sent in client bodies. Changes made through the Zones API will always yield valid zone data, as the API will reject records with wrong data. DNSSEC-enabled zones should be :ref:`rectified ` after changing the zone data. This can be done by the API automatically after a change when the :ref:`metadata-api-rectify` metadata is set. When creating or updating a zone, the "api_rectify" field of the :json:object:`Zone` can be set to `true` to enable this behaviour. 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``, ``rrsets`` or ``zone``. Examples -------- Listing all zones ^^^^^^^^^^^^^^^^^ .. code-block:: http GET /api/v1/servers/localhost/zones HTTP/1.1 X-API-Key: secret Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json [{"account": "", "dnssec": false, "edited_serial": 2022040504, "id": "example.org.", "kind": "Native", "last_check": 0, "masters": [], "name": "example.org.", "notified_serial": 0, "serial": 2022040504, "url": "/api/v1/servers/localhost/zones/example.org."}] Creating new zone ^^^^^^^^^^^^^^^^^ .. code-block:: http POST /api/v1/servers/localhost/zones HTTP/1.1 X-API-Key: secret Content-Type: application/json {"name": "example.org.", "kind": "Native", "masters": [], "nameservers": ["ns1.example.org.", "ns2.example.org."]} Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json {"account": "", "api_rectify": false, "dnssec": false, "edited_serial": 2022040501, "id": "example.org.", "kind": "Native", "last_check": 0, "master_tsig_key_ids": [], "masters": [], "name": "example.org.", "notified_serial": 0, "nsec3narrow": false, "nsec3param": "", "rrsets": [{"comments": [], "name": "example.org.", "records": [{"content": "a.misconfigured.dns.server.invalid. hostmaster.example.org. 2022040501 10800 3600 604800 3600", "disabled": false}], "ttl": 3600, "type": "SOA"}, {"comments": [], "name": "example.org.", "records": [{"content": "ns1.example.org.", "disabled": false}, {"content": "ns2.example.org.", "disabled": false}], "ttl": 3600, "type": "NS"}], "serial": 2022040501, "slave_tsig_key_ids": [], "soa_edit": "", "soa_edit_api": "DEFAULT", "url": "/api/v1/servers/localhost/zones/example.org."} Listing a zone ^^^^^^^^^^^^^^ .. code-block:: http GET /api/v1/servers/localhost/zones/example.org. HTTP/1.1 X-API-Key: secret Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json {"account": "", "api_rectify": false, "dnssec": false, "edited_serial": 2022040501, "id": "example.org.", "kind": "Native", "last_check": 0, "master_tsig_key_ids": [], "masters": [], "name": "example.org.", "notified_serial": 0, "nsec3narrow": false, "nsec3param": "", "rrsets": [{"comments": [], "name": "example.org.", "records": [{"content": "a.misconfigured.dns.server.invalid. hostmaster.example.org. 2022040501 10800 3600 604800 3600", "disabled": false}], "ttl": 3600, "type": "SOA"}, {"comments": [], "name": "example.org.", "records": [{"content": "ns1.example.org.", "disabled": false}, {"content": "ns2.example.org.", "disabled": false}], "ttl": 3600, "type": "NS"}], "serial": 2022040501, "slave_tsig_key_ids": [], "soa_edit": "", "soa_edit_api": "DEFAULT", "url": "/api/v1/servers/localhost/zones/example.org."} Deleting a zone ^^^^^^^^^^^^^^^ .. code-block:: http DELETE /api/v1/servers/localhost/zones/example.org. HTTP/1.1 X-API-Key: secret Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 204 No Content Creating new RRset ^^^^^^^^^^^^^^^^^^ .. code-block:: http PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1 X-API-Key: secret Content-Type: application/json {"rrsets": [{"name": "test.example.org.", "type": "A", "ttl": 3600, "changetype": "REPLACE", "records": [{"content": "192.168.0.5", "disabled": false}]}]} Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 204 No Content Deleting a RRset ^^^^^^^^^^^^^^^^^^ .. code-block:: http PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1 X-API-Key: secret Content-Type: application/json {"rrsets": [{"name": "test.example.org.", "type": "A", "changetype": "DELETE"}]} Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 204 No Content Rectifying a zone ^^^^^^^^^^^^^^^^^ .. code-block:: http PUT /api/v1/servers/localhost/zones/example.org./rectify HTTP/1.1 X-API-Key: secret Will yield a response similar to this (several headers omitted): .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json {"result": "Rectified"}