DNS API

Authentication

Basic auth credentials must be supplied with every request to this API. The username is the zone name. The password can be retrieved from the Dynamic DNS Tab in the Domain control panel.

Base URL

API requests are performed against the base URL https://www.syse.no/api/dns. The relative path to each operation is given below, together with the method verb.

Operations

List custom records

GET /{zone}

Returns a JSON Array of all custom dns records. Please note that service records for managed services are not returned, but you can override them by providing a custom record which shadows the service record. Example output with one list element:

[
    {
        "id": "1234",
        "content": "127.0.0.1",
        "active": false,
        "prio": 10,
        "ttl": 10800,
        "prefix": "www",
        "type": "A"
    }
]

Create custom record

POST /{zone}

Create a new custom record. An ID is generated and returned with the response. Example payload:

{
    "content": "127.0.0.1",
    "active": false,
    "prio": 10,
    "ttl": 10800,
    "prefix": "www",
    "type": "A"
}

Update custom record

PUT /{zone}/{id}

Update an existing custom record. The id in the URL must match the id in the object. Example payload:

{
    "id": "1234",
    "content": "127.0.0.1",
    "active": false,
    "prio": 10,
    "ttl": 10800,
    "prefix": "www",
    "type": "A"
}

Delete custom record

DELETE /{zone}/{id}

Delete an existing custom record.

Attributes, record types and validation rules

Below you'll find a list of attributes common for all operations, along with a list of valid record types and the spesific validation rule for each record type.

Attributes

Name	Type	Notes	Default	Description
prefix	string	required	-	The prefix this record applies to, e.g. ‘www’.
type	string	required	-	The type of DNS records, e.g. 'A’ or 'TXT’.
active	boolean	required	true	If set to false, the corresponding DNS entry will disappear from the zones DNS.
content	string	-	-	Must not exceed 65535 characters and may only contain printable ASCII characters.
ttl	integer	-	3600	Can be set from 60 seconds (1 minute) to 259200 seconds (3 days). Default is always 3600 seconds (1 hour). Customer UI implemtors should probably not allow TTLs lower than 600s (10 minutes).
prio	integer	-	0	(If present) must be an integer between 0 and 65535.

Supported record types

• CNAME
• A
• AAAA
• MX
• TXT
• SRV
• SSHFP
• TLSA
• AFSDB
• NAPTR
• NS
• DS
• LOC
• CAA
• SVCB/HTTPS

Definitions

Printable ASCII	Matches ^[ -~]*$
Valid host name	Matches ^((\*\.)?((([a-z0-9-]*[a-z0-9])\.)+[a-z]+))$
Valid DNS name	Matches ^(([_a-z0-9]([_a-z0-9-]*[a-z0-9])?\.)*([_a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+([a-z]([a-z0-9-]*[a-z])))$

Note that hostnames accepts wildcards for some record types.

Validation rules

In general

• If prefix is non-empty, prefix.{zone} must be a valid DNS name and the total length must not exceed 255 characters. Different restrictions apply for certain records types. Note: some record types must satisfy the valid hostname requirement, which allows for wildcard records (starting with an asterisk) that does not satisfy the valid DNS name requirement. (hostnames cannot begin or end with a hyphen). See below.
• content must not exceed 65535 characters and may only contain printable ASCII characters. I.e. it must match the regular expression ^[ -~]*$.
• ttl is an integer and if present, can be set from 600 seconds (10 minutes) to 259200 seconds (3 days). Default is always 3600 seconds (1 hour).
• IDNA domains is allowed (punycoded) following the ASCII Compatible Encoding (ACE) encoding scheme. The first four letters of an IDNA domain must be xn--. -- is not alloweded in 3rd and 4th position, unless prefixed with xn.

CNAME

• prefix cannot be empty.
• content must be a valid DNS name.[^singlelabelcontent]
• Cannot point to itself, i.e. test.doma.in -> test.doma.in
• Cannot create cyclic references (i.e. the principle a -> b -> c -> a)

Conflicts with

• Any type with same prefix.

A

• content must be a valid IPv4 address.
• prefix + . + zone (or just zone if prefix is empty) must be a valid hostname[^underscoreinprefix]

Conflicts with

• CNAME, WEBFORWARD* with same prefix.
• A with same prefix and content.

AAAA

• content must be a valid IPv6 address.
• prefix + . + zone (or just zone if prefix is empty) must be a valid hostname[^underscoreinprefix]

Conflicts with

• CNAME, WEBFORWARD* with same prefix.
• AAAA with same prefix and content.

MX

• content must be a valid hostname or a . (Null MX record. See RFC 7505)
• prio (if present) must be an integer between 0 and 65535. Default prio is 0.
• prefix + . + zone (or just zone if prefix is empty) must be a valid hostname (except for the Null MX record)

Conflicts with

• CNAME with same prefix.
• MX with same prefix and content.
• MX with . as content (Null MX record) conflicts with all other MX records with the same prefix

TXT

• content is required

Conflicts with

• CNAME with same prefix.
• TXT with same prefix and content.

SRV

• prefix must be on the form _<service>._<protocol> or _<service>._<protocol>.<additional prefixes> . E.g. _sip._tcp, _minecraft._tcp.myserver, _sip._tls.abcd.efgh. Formally it must match ^_[a-z0-9-]+\._[a-z0-9-]+(\._?[a-z0-9-]+)*
• prio (if present) must be an integer between 0 and 65535. Default prio is 0.
• content must be on the form <weight> <port> <target>, where <weight> and <port> are integers and <target> is a valid host name. Note the absence of an ending dot.
• In SRV prefixes, hyphens cannot be adjecent to other hyphens

Conflicts with

• CNAME with same prefix.
• SRV with same prefix and same content.

SSHFP

• content must be on the form <algorithm> <type> <fingerprint>, where <algorithm> and <type> are non-negative integers and <fingerprint> is a hexadecimal string. Formally it must match ^[\d]+\s+[\d]+\s+[0-9a-f]+$.
• prefix + . + zone (or just zone if prefix is empty) must be a valid hostname

Conflicts with

• CNAME with same prefix.
• SSHFP with same prefix and content.

TLSA

• prefix must be on the form _<port>._<protocol> or _<port>._<protocol>.<additional prefixes>. E.g. _443._tcp. Formally it must match ^_[0-9]+\._[a-z0-9-]+
• content must be on the form <usage> <selector> <matching type> <fingerprint>, where <usage>, <selector>, and <matching type> are selected, non-negative integers and <fingerprint> is a hexadecimal string. Formally it must match ^[0-3]\s+[0-1]\s+[0-3]\s+[0-9a-f]+$.

Conflicts with

• CNAME with same prefix
• TLSA with same prefix and content

AFSDB

• content must be on the form <integer> <valid DNS name>, where integer can be either 1 or 2.

Conflicts with

• CNAME with same prefix
• AFSDB with same prefix and same content

LOC

• content must be on the form d1 [m1 [s1]] {"N"|"S"} d2 [m2 [s2]] {"E"|"W"} alt["m"] [siz["m"] [hp["m"] [vp["m"]]]] (see RFC1876)

Conflicts with

• CNAME with same prefix
• LOC with same prefix and same content

CAA

• content must be on the form <flag> <tag> "<value>", where flag is a byte flag value

Conflicts with

• CNAME with same prefix
• CAA with same prefix and same content

SVCB/HTTPS

• content must be on the form <prio> <target> [<params>] If prio is 0, the record is in AliasMode and and only have a target but no params. This mode can be used to create the equivalent of a CNAME record on the zone apex. If prio is 1, the record is in ServiceMode and takes both target and params. Only the valid params (alpn, no-default-alpn, ech, port, ipv4hint, ipv6hint, mandatory and keyXXXXX (where XXXXX is an integer between 1 and 65535 with no leading zero) is allowed). See RFC draft for more information.

Conflicts with

• CNAME with same prefix
• SVCB/HTTPS with same prefix and same content