Knot-DNS-REST

About

Knot DNS REST is a Python application that mediates communication between a Knot DNS server and the HTTP REST API.

REST API

For call of remote process you should use custom client. But for testing, you can use curl command for example:

curl -X PUT -d "name=dns1.example.com." -d "type=AAAA" -d "ttl=3600" -d "data=123.45.67.89" 127.0.0.1:8080/zones/example.com./records  | jq
# NOTE: This is just an example, this might delete record from you zone. For pretty JSON output use 'jq'
curl -X DELETE -d "name=dns1.example.com." -d "type=AAAA" 127.0.0.1:8080/zones/example.com./records  | jq

REST clients utils

Kano has made a nice python util for interfacing with the REST API in a simple manner.

knotctl, also available as a deb package here (NOTE: you'll need requests=<2.27, See this issue

Hacky shell script knot_rest.sh (NOTE: depends on jq)

To obtain authorization token, send following request where -u are users credentials in format <username>:<password>.

curl -u dev:dev 127.0.0.1:5000/user/login

For sending request as logged in user, add authorization token in packet header like this:

curl -H "Authorization: Bearer <token>" ...

Only an existing user can register users. The token of the logged-in user is required, as well as the username and password of the new user.

curl -X POST -H "Authorization: Bearer <token>" -d "username=<username>" -d "password=<password> 127.0.0.1:5000/user/register

Commands

In the tables below, parameters labeled path are specified in URL path as /zones/example.com/records/dns1.example.com/A. Parameters labeled query are specified in URL query as /zones/example.com/records?name=dns1.example.com&rtype=A. Parameters labeled HTTP POST data are stored in HTTP header (the method of transmission depends on the client).

GET /zones/<zone>

List all (or specified) zones on a server.

Parameters:

name	description	mandatory	path	query / HTTP POST data
zone	Zone name		x	x

Status codes:

200 OK - Successful
404 Not Found - Requested item was not found
500 Internal Server Error - The server has encountered a situation it does not know how to handle

GET /zones/<zone>/records/<name>/<rtype>/<data>/<ttl>

List all records in a zone that match parameters.

Parameters:

name	description	mandatory	path	query / HTTP POST data
zone	Zone name	x	x
name	Record domain name (URL encoded)		x	x
rtype	Record type		x	x
data	Record data (URL encoded)		x	x
ttl	Record TTL		x	x

Status codes:

200 OK - Successful
404 Not Found - Requested item was not found
500 Internal Server Error - The server has encountered a situation it does not know how to handle

PUT /zones/<zone>/records/<name>/<rtype>/<data>/<ttl>

Add record in a zone. Return zone after changes.

Parameters:

name	description	mandatory	path	query / HTTP POST data
zone	Zone name	x	x
name	Record domain name (URL encoded)		x	x
rtype	Record type		x	x
data	Record data (URL encoded)		x	x
ttl	Record TTL		x	x

Status codes:

201 CREATED - Successful
400 Bad Request - Missing or malformed data in a request
409 Conflict - Record already exists
500 Internal Server Error - The server has encountered a situation it does not know how to handle

PATCH /zones/<zone>/records/<name>/<rtype>/<data>

Change record in a zone. Returns changed record.

Parameters:

name	description	mandatory	path	query / HTTP POST data
zone	Zone name	x	x
name	Record domain name (URL encoded)	x	x
rtype	Record type	x	x
data	Record data (URL encoded)	x	x
name	New record domain name (URL encoded)			x
rtype	New record type			x
data	New record data (URL encoded)			x
ttl	New record TTL			x

Status codes:

200 OK - Successful
400 Bad Request - Missing or malformed data in a request
404 Not Found - Record don't exist
500 Internal Server Error - The server has encountered a situation it does not know how to handle

DELETE /zones/<zone>/records/<name>/<rtype>/<data>/<ttl>

Delete records in a zone matching the filter. Return zone after update.

Parameters:

name	description	mandatory	path	query / HTTP POST data
zone	Zone name	x	x
name	Record domain name (URL encoded)		x	x
rtype	Record type		x	x
data	Record data (URL encoded)		x	x
ttl	Record TTL		x	x

Status codes:

200 OK - An array of records
400 Bad Request - Trying to delete SOA
404 Not Found - Requested item was not found
500 Internal Server Error - The server has encountered a situation it does not know how to handle

Objects

Error

{
  "Code": 404,
  "Description": "Zone not found",
  "Error": "Not found"
}

Description - Description of the source of the error
Error - HTTP error code name

Zone

{
  "name": example.com.,
  "url": "/zones/example.com.,
  "serial": 1,
  "records": [
    {
      "data": "dns1.example.com. hostmaster.example.com. 1 21600 3600 604800 86400",
      "name": "example.com.",
      "rtype": "SOA",
      "ttl": "3600",
      "url": "/zones/example.com./records/example.com./SOA/dns1.example.com.%20hostmaster.example.com.%201%2021600%203600%20604800%2086400"
    }
  ]
}

name - Zone name
url - Path that uniquely identifies the zone object
serial - Serial number of the zone
records - Array of the records relevant to the zone

Record

{
  "data": "dns1.example.com. hostmaster.example.com. 2010111227 21600 3600 604800 86400",
  "name": "example.com.",
  "rtype": "SOA",
  "ttl": "3600",
  "url": "/zones/example.com./records/example.com./SOA/dns1.example.com.%20hostmaster.example.com.%202010111227%2021600%203600%20604800%2086400"
}

data - Record data
name - Record name
rtype - Record type
ttl - Record time to live
url - Path that uniquely identifies the record object

Knot-DNS-REST

About

REST API

REST clients utils

Login/Registration

Commands

Objects