added examples to Servers and Zones endpoints, fixed order in TSIGKeys endpoint

diff --git a/docs/http-api/server.rst b/docs/http-api/server.rst
index ce64211896b66a82f51b75759b7cbaaa1f3d129c..00b1de982e890682f6d21f7302f10adbfac6642c 100644 (file)
--- a/docs/http-api/server.rst
+++ b/docs/http-api/server.rst
@@ -15,3 +15,40 @@ Objects
 -------
 .. openapi:: swagger/authoritative-api-swagger.yaml
   :definitions: Server
+
+Examples
+--------
+
+Listing all servers
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: http
+
+  GET /api/v1/servers 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
+  
+  [{"autoprimaries_url": "/api/v1/servers/localhost/autoprimaries{/autoprimary}", "config_url": "/api/v1/servers/localhost/config{/config_setting}", "daemon_type": "authoritative", "id": "localhost", "type": "Server", "url": "/api/v1/servers/localhost", "version": "4.6.1", "zones_url": "/api/v1/servers/localhost/zones{/zone}"}]
+
+Listing a server
+^^^^^^^^^^^^^^^^
+
+.. code-block:: http
+
+  GET /api/v1/servers/localhost 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
+  
+  {"autoprimaries_url": "/api/v1/servers/localhost/autoprimaries{/autoprimary}", "config_url": "/api/v1/servers/localhost/config{/config_setting}", "daemon_type": "authoritative", "id": "localhost", "type": "Server", "url": "/api/v1/servers/localhost", "version": "4.6.1", "zones_url": "/api/v1/servers/localhost/zones{/zone}"}

diff --git a/docs/http-api/tsigkey.rst b/docs/http-api/tsigkey.rst
index dce4448684c70bb51a3ebfd3d259ae93dcf5b72e..0c1bab429843c20a8a83fd856340e5dc35fe16e4 100644 (file)
--- a/docs/http-api/tsigkey.rst
+++ b/docs/http-api/tsigkey.rst
@@ -4,6 +4,18 @@ TSIGKeys
 
 TSIGKeys can be manipulated via the API.
 
+TSIGKey Endpoints
+-----------------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+  :paths: /servers/{server_id}/tsigkeys /servers/{server_id}/tsigkeys/{tsigkey_id}
+
+Objects
+-------
+
+.. openapi:: swagger/authoritative-api-swagger.yaml
+  :definitions: TSIGKey
+
 Examples
 --------
 
@@ -44,16 +56,4 @@ Modifying the key material
   Content-Type: application/json
 
   {"algorithm": "hmac-sha256", "id": "mytsigkey.", "key": "GQNyFy1QagMUarHmiSgsIJajghdTGJGVcN5TRVwgbclzxGyhQR1uYLCOyJ/uj9uj12jyeLwzJuW12wCI9PYv7Q==", "name": "mytsigkey", "type": "TSIGKey"}
-
-
-TSIGKey Endpoints
------------------
-
-.. openapi:: swagger/authoritative-api-swagger.yaml
-  :paths: /servers/{server_id}/tsigkeys /servers/{server_id}/tsigkeys/{tsigkey_id}
-
-Objects
--------
-
-.. openapi:: swagger/authoritative-api-swagger.yaml
-  :definitions: TSIGKey
+  

diff --git a/docs/http-api/zone.rst b/docs/http-api/zone.rst
index ddda71559fb61fcdf4310ac0c3281d705203f742..3e6addc95ffcba9417a35468d1f29200be1ead81 100644 (file)
--- a/docs/http-api/zone.rst
+++ b/docs/http-api/zone.rst
@@ -44,3 +44,126 @@ 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/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/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"}
+