API of DNS hosting. For DNS-master and Secondary services Table of contents

(1)

API of DNS hosting. For DNS-master and Secondary services

1. Introduction

HTTPS is a transport protocol to call API functions. API of DNS hosting is implemented on REST base with XML format support in requests and

responses.

(4)

Each requesting is atomic and synchronous, i.e. all requests are independent from each other. All operations are also synchronous: The result s returned

immediately, there are no intermediate states during operation.

API of DNS hosting enables the developers to create their own applications for further operation with DNS-master and Secondary services. The

development and further use of the application can be implemented as part of one and the same agreement upon registration of the application on

RU-CENTER OAuth-server

. As a result of registration access details will be issued for the developed application.

2. Setting access area of application for issuing token

For issuance of token access areas and rights are set via '

scope'

setting.

Token issued without

scope

setting will not work due to absence of the area.

In general

scope

setting is a list in format

<method>:<url path> <method>:<url path> <method>:<url path>.

List items are separated with

spaces. Methods (

) specifying access rights to the set scope

and <url path>

, specifying the access area are colon-separated.

Setting

may have the following values:

GET

– data read access;

PUT

– data publication access;

POST

– data modification access;

DELETE

– published data deletion access

or may be set

by regular expression

, for example:

GET|POST

– data read and modification access;

GET|PUT

– data read and publication access;

GET|PUT|DELETE

– data read, publication and deletion access;

GET|POST|DELETE

– data read, modification and deletion data;

.+

– full access

(5)

Setting

is set by

regular expression

}with the limitation set for characters

^

and

$

without specification of the domain and protocol

(

https://api.nic.ru

). For DNS hosting it always starts from

/dns-master/

:

/dns-master/.+

for granting access to all DNS hosting services;

/dns-master/zones/<zone>(/.+)?

for granting access to a specific zone

<zone>

;

/dns-master/services/<service>(/.+)?

for granting access to a specific service

;

/dns-master/services/<service>/zones/<zone>(/.+)?

for granting access to particular zone

<zone>

on particular service

2.1 The examples of the scope setting values for token issuance for DNS hosting services:

• scope=GET:/dns-master/.+

limitation only for data read for all DNS hosting services under the agreement;

• scope=POST:/dns-master/.+

limitation only for data modification for all DNS hosting services under the agreement;

• scope=(GET|PUT):/dns-master/services/<service>/.+

access for data read and publication to specific service

;

• scope=PUT:/dns-master/services/<service>/zones/<zone1>(/.+)? POST:/dns-master/services/<service>/zones/<zone2>(/.+)?

access for data publication to zone

<zone1>

and data editing to zone

<zone2>

placed under service

.

List items in

scope setting

(

PUT:/dns-master/services/<service>/zones/<zone1>(/.+)? and

POST:/dns-master/services/<service>/zones/<zone2>(/.+)?

)

are space-separated;

• scope=(GET|POST|DELETE):/dns-master/services/<service>/zones/<zone>(/.+)?

data read, modification and deletion access to zone

<zone>

placed under service

;

• scope=GET:/dns-master/services/<service>/.+

only data read limitation for service

;

• scope=GET:/dns-master/services/<service1>/zones/<zone1>(/.+)? PUT:/dns-master/services/<service2>/zones/<zone2>(/.+)? (POST|DELETE):/dns-master/services/<service3>/zones/<zone3>(/.+)?

(6)

data read access to zone

<zone1>

placed under service

, data add access to zone

<zone2>

placed under service

<service2> and data editing and deletion access to zone <zone3> placed under service <service3>.

List items in

scope setting

(

GET:/dns-master/services/<service1>/zones/<zone1>(/.+)?

,

PUT:/dns-master/services/<service2>/zones/<zone2>(/.+)?

and

(POST|DELETE):/dns-master/services/<service2>/zones/<zone2>(/.+)?

)

are space-separated;

• scope=POST:.+/zones/<zone>(/.+)?

data editing access to zone

<zone>

;

• PUT:/dns-master/services/service/.+

data add access to specific service

;

• scope=.+:/dns-master/.+

full access to all DNS hosting services under the agreement.

2.2 Examples of requests to obtain token by login and password through basic HTTP authorization

When sending request for obtaining token, standard encoding rules are used.

•

The request for obtaining read-only token to all DNS hosting services under the agreement will have the following look:

POST https://api.nic.ru/oauth/token HTTP/1.1 Authorization: Basic <base64-encoded-string> Content-Type: application/x-www-form-urlencoded

grant_type=password&username=login&password=pass&scope=GET%3A%2Fdns-master%2F.%2B

Request example:

POST https://api.nic.ru/oauth/token HTTP/1.1 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded

(7)

Settings submitted in request:

grant_type

- type of response. Required setting, setting

grant_type

will always be assigned with value

password

;

username

- user login. The agreement number is used as user login, for example,

username=123/NIC-REG

;

password

- user password. Administrative or technical passwords may be used, for example,

password=qwerty.

•

Request for obtaining token with editing access authorization to zone

<zone>

placed under service

:

POST https://api.nic.ru/oauth/token HTTP/1.1 Authorization: Basic <base64-encoded-string> Content-Type: application/x-www-form-urlencoded

grant_type=password&username=login&password=pass&scope=POST%3A%2Fdns-master%2Fservices%2F<service>%2Fzones%2F<zone>(%2F.%2B)%3F

Request example:

POST https://api.nic.ru/oauth/token HTTP/1.1 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded

grant_type=password&username=123/NIC-REG&password=qwerty&scope=POST%3A%2Fdns-master%2Fservices%2FMYSERVICE%2Fzones%2FMYDOMAIN(%2F.%2B)%3F

3. Description of general requests to API of DNS hosting

3.1 Obtaining list of DNS hosting services under agreement

The format of request for obtaining the list of all DNS hosting services under the agreement has the following look:

GET https://api.nic.ru/dns-master/services?token=<token>

The second request option:

GET https://api.nic.ru/dns-master/services Authorization: Bearer <token>

(8)

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

<?xml version="1.0" encoding="UTF-8" ?> <response>

<status>success</status> <data>

</data> </response>

Settings submitted in request:

admin -

agreement number;

domains-limit -

the allowed number of domain zones per plan under which the service is delivered;

domains-num -

the number of domain zones placed under the service;

name -

service identifier;

rr-limit –

the allowed number of resource records per plan, under which the service is provided (for DNS-master services);

rr-num -

the number of added resource records (for DNS-master services);

tariff -

plan under which the service is delivered;

payer –

payer;

enable="true" –

the service is delivered;

has-primary="true" –

DNS-master service;

has-primary="false" –

Secondary service

(9)

3.2.1 Obtaining the list of all domain zones irrespective of the services they are placed under

The format of request for obtaining the list of all domain zones has the following look:

GET https://api.nic.ru/dns-master/zones Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/zones?token=<token>

3.2.2 Obtaining the list of all domain zones under specific service

The format of request for obtaining the list of all domain zones has the following look:

GET https://api.nic.ru/dns-master/services/<service>/zones Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service>/zones?token=<token>

Settings submitted in request:

- service identifier under which list of domain zones should be obtained.

Request example:

GET https://api.nic.ru/dns-master/services/MYSERVICE/zones Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

(10)

</data> </response>

Settings submitted in request:

admin -

agreement number;

id -

numeric zone identifier;

name –

zone name in Punycode;

idn-name –

IDN

of domain zone;

service –

service identifier;

has-changes="true" –

zone has changes unloaded to DNS servers;

has-changes="false" –

zone has no changes unloaded to DNS servers;

enable="true" –

zone is enabled and loaded to DNS servers;

enable="true" –

zone is disabled and not loaded to DNS servers;

0has-primary="true" –

DNS-master service;

Secondary service

3.2.3 Zone creation under the service

The format of request for domain zone placement under specific service has the following look:

PUT https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name> Authorization: Bearer <token>

(11)

For DNS-master services the request body may contain zone body.

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

PUT https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

</data> </response>

Settings submitted in request:

admin

– agreement number;

id

- numeric zone identifier;

idn-name

– IDN of zone;

name

– zone name in Punycode;

service

– service identifier;

zone has changes unloaded to DNS servers;

zone has no changes unloaded to DNS servers;

enable="true" –

zone is enabled and loaded to DNS servers;

(12)

enable="true" –

zone is disabled and not loaded to DNS servers;

0has-primary="true" –

DNS-master service;

Secondary service

payer

- payer

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

<error code="code">error text</error> </errors>

3.2.4 Domain zone creation with service auto-selection

Domain zone is created under arbitrary service, where there is an opportunity to place additional zone and resource records, if request body is present

in the zone body.

The format of request for domain zone creation with DNS-master service auto-selection has the following look:

PUT https://api.nic.ru/dns-master/zones/primary/<zone_name> Authorization: Bearer <token>

The format of request for domain zone creation with Secondary service auto-selection has the following look:

PUT https://api.nic.ru/dns-master/zones/secondary/<zone_name> Authorization: Bearer <token>

Settings submitted in request:

(13)

<token>

- access token

Request example:

PUT https://api.nic.ru/dns-master/zones/primary/MYDOMAIN.RU Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

</data> </response>

Settings submitted in request:

admin

– agreement number;

id

- numeric zone identifier;

idn-name

– IDN of zone;

name

– zone name in Punycode;

service

– service identifier;

the zone has changes unloaded to DNS servers;

the zone has no changes unloaded to DNS servers;

enable="true" –

zone is enabled and loaded to DNS servers;

enable="true" –

zone is disabled and not loaded to DNS servers;

0has-primary="true" –

DNS-master service;

(14)

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

3.2.5 Domain zone transfer from one DNS hosting service to another

When domain zone is transferred from one DNS hosting service to another one there is no need to transfer zone body in the request body.

The format of the request for domain zone transfer has the following look:

POST https://api.nic.ru/dns-master/services/<service>/zones/<zone_name>/move/<new_service> Authorization: Bearer <token>

Settings submitted in request:

- service identifier from which domain zone should be transferred.

<new_service>

- service identifier to which domain zone should be transferred;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/move/NEWSERVICE Authorization: Bearer 123123123123

(15)

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

3.2.6 Domain zone deletion from the service

The format of the request for domain zone deletion has the following look:

DELETE https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name> Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

DELETE https://api.nic.ru/dns-master/services/TESTSERVICE/zones/TEST.COM Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

<status>success</status> <data/>

(16)

If any errors occurred, HTTP with the error code 200 will be returned in the response and the response body will have the following look:

3.2.7 Obtaining the list of addresses, from which zone XFER is permitted

The format of request for obtaining the list of addresses from which zone XFER is permitted has the following look:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/xfer Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/xfer?token=<token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/xfer Authorization: Bearer 123123123123

(17)

<?xml version="1.0" encoding="UTF-8" ?> <response> <status>success</status> <data> <address>12.12.12.12</address> <address>12.12.12.12/29</address> <address>127.0.0.1</address> </data> </response>

Value "any" may be specified instead of the address, when the response body will have the following look

:

<?xml version="1.0" encoding="UTF-8" ?> <response> <status>success</status> <data> <address>any</address> </data> </response>

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

<error code="4097">Access token expired or not found</error> </errors>

</response>

3.2.8 Changing the list of addresses, from which zone XFER is permitted

The format of request for changing the list of addresses from which zone XFER is permitted has the following look:

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/xfer Authorization: Bearer <token>

(18)

<?xml version="1.0" encoding="UTF-8" ?> <request> <address>address1</address> <address>address2</address> <address>addressN</address> </request>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

address1, address2, …, addressN

- IPv4 addresses, from which XFER is permitted (

value "any" may be assigned to "address" setting

)

Request example:

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/xfer Authorization: Bearer 123123123123 <?xml version="1.0" encoding="UTF-8" ?> <request> <address>12.12.12.12</address> <address>12.12.12.12/29</address> <address>127.0.0.1</address> </request>

The second request option:

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/xfer Authorization: Bearer 123123123123 <?xml version="1.0" encoding="UTF-8" ?> <request> <address>any</address> </request>

(19)

<status>success</status> </response>

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

4. Description of requests to API for DNS master services

4.1 Working with zone files

4.1.1 Obtaining current zone file for the domain

The format of the request for obtaining current zone file for the domain zone has the following look:

GET https://api.nic.ru/dns-master/services/<service>/zones/<zone> Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service>/zones/<zone>?token=<token>

(20)

- service identifier;

<zone>

- domain zone name;

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/TESTSERVICE/zones/TEST.RU Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body contains the current version of the domain zone:

HTTP/1.1 200 OK

x-request-id: 201304011836.55@dns Connection: close

Transfer-Encoding: chunked

Content-Type: text/plain; charset=UTF-8

$TTL 3600

$ORIGIN TEST.RU

TEST.RU 3600 IN SOA ns3-l2.nic.ru. support.test.ru. ( 65012710 ; serial 14400 ; refresh 3600 ; retry 2592000 ; expire 600) $ORIGIN TEST.RU. @ NS ns8-l2.nic.ru. NS ns3-l2.nic.ru. NS ns4-l2.nic.ru. NS ns4-cloud.nic.ru NS ns8-cloud.nic.ru MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU.

(21)

$ORIGIN MAIL.TEST.RU. @ MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU. $ORIGIN TEST.RU. @ TXT "v=spf1 redirect=nicmail.ru" MAIL TXT "v=spf1 redirect=nicmail.ru" @ A 194.85.88.226 MAIL A 194.85.88.226 @ A 194.85.88.228 MAIL A 194.85.88.228 @ A 194.85.88.231 MAIL A 194.85.88.231 @ A 194.85.88.239 MAIL A 194.85.88.239 @ A 194.85.88.240 MAIL A 194.85.88.240 @ A 194.85.88.241 MAIL A 194.85.88.241 test DNAME test.ru.

@ TXT "1231" "12"

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

<error code="Code">Error text</error> </errors>

(22)

In several errors occurred, all errors with the correspondent codes will be transferred in the response body.

4.1.2 zone file upload

The request body shall contain zone file contents.

The format of the zone file upload request has the following look:

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name> Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/MYDOMAIN.RU Accept-Charset: UTF-8

Accept-Language: en

Authorization: Bearer 123123123123 Content-Type: text/plain; charset=UTF-8

$TTL 3600 $ORIGIN RU.

MYDOMAIN 3600 IN SOA ns3-l2.nic.ru. support.nic.ru. ( 65012710 ; serial 14400 ; refresh 3600 ; retry 2592000 ; expire 600) $ORIGIN MYDOMAIN.RU. @ NS ns8-l2.nic.ru.

(23)

NS ns3-l2.nic.ru. NS ns4-l2.nic.ru. MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU. $ORIGIN MAIL.MYDOMAIN.RU. @ MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU. $ORIGIN MYDOMAIN.RU. @ TXT "v=spf1 redirect=nicmail.ru" MAIL TXT "v=spf1 redirect=nicmail.ru" @ A 194.85.88.226 MAIL A 194.85.88.226 @ A 194.85.88.228 MAIL A 194.85.88.228 @ A 194.85.88.231 MAIL A 194.85.88.231 @ A 194.85.88.239 MAIL A 194.85.88.239 @ A 194.85.88.240 MAIL A 194.85.88.240 @ A 194.85.88.241 MAIL A 194.85.88.241 mydomain DNAME mydomain.ru.

@ TXT "1231" "12"

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

<status>success</status> <data/>

</response>

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

(24)

4.2 Cancellation of introduced changes in zone

The format of the request for cancellation of the introduced changes has the following look:

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/rollback Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

POST https://api.nic.ru/dns-master/services/TESTSERVICE/zones/TEST.RU/rollback Authorization: Bearer 123123123123

In case of a success HTTP 200 will be returned. The response body has the following look:

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

(25)

</response>

4.3 Working with zone versions

4.3.1 Fixing zone version and zone upload to DNS servers

Request format for fixing zone version and zone upload to DNS has the following look:

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/commit Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/commit Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

(26)

</response>

4.3.2 Obtaining the list of zone versions

The format of the request for obtaining the list of versions has the following look:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/revisions Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/revisions?token=<token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/MYSERVICE/zones/EXAMPLE.COM/revisions Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

(27)

</data>

</response>

Settings submitted in request:

revision date

– data saving;

ip

– which IP-address the version was uploaded from;

number

– version number

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

4.3.3 Zone version view

The request format for version view has the following look:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/revisions/<revision> Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/revisions/<revision>?token=<token>

(28)

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

- version number;

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/revisions/3 Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. Request body contains zone file and has the following look:

HTTP/1.1 200 OK

x-request-id: 201304011836.55@dns Connection: close

Transfer-Encoding: chunked

Content-Type: text/plain; charset=UTF-8

$TTL 3600

$ORIGIN test.ru.

test.ru. 3600 IN SOA ns3-l2.nic.ru. saatchiceo.test.ru. ( 65012710 ; serial 7200 ; refresh 3600 ; retry 2592000 ; expire 600 ; minimum ) test.ru. IN NS ns4-l2.nic.ru. test.ru. IN NS ns3-l2.nic.ru. test.ru. IN NS ns8-l2.nic.ru. test.ru. IN NS ns4-cloud.nic.ru. test.ru. IN NS ns8-cloud.nic.ru. test.ru. IN A 87.117.10.65 www.test.ru. IN CNAME test.ru.

(29)

test.test.ru. IN CNAME test.ru. test.test.ru. IN CNAME test.ru.

In response body IDN-domains are converted to Punycode.

If any errors occurred, HTTP with the error code will be transferred in the response and the response body will have the following look:

</response>

4.3.4 Installation of the selected zone version as the current one

The request format for installation of zone version as the current one has the following look:

PUT https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/revisions/<revision> Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

- version number;

<token>

- access token

Request example:

PUT https://api.nic.ru/dns-master/services/MYSERVICE/zones/EXAMPLE.COM/revisions/3 Authorization: Bearer 123123123123

(30)

If any errors occurred, HTTP with the error code will be transferred in the response and the response body will have the following look:

</response>

4.4 $TTL value management

4.4.1 Set $TTL value

Default TTL = 3600. To set own $TTL value, request should be transferred.

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/default-ttl Authorization: Bearer <token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

ttl

- TTL value

(31)

POST https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/default-ttl Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

4.4.2 Obtaining current $TTL value

The format of the request for obtaining the current TTL value has the following look:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/default-ttl Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/default-ttl?token=<token>

Settings submitted in request:

<service_id>

- service identifier;

(32)

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/MYSERVICE/zones/EXAMPLE.COM /default-ttl Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

<?xml version="1.0" encoding="UTF-8" ?> <response> <status>success</status> <data> <default-ttl>3600</default-ttl> </data> </response>

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

4.5 Working with resource records

4.5.1 Adding resource record

The format of the request for adding resource record has the following look:

PUT https://api.nic.ru/dns-master/services/<service>/zones/<zone>/records Authorization: Bearer <token>

(33)

<?xml version="1.0" encoding="UTF-8" ?> <request> <rr-list> (<rr>...</rr>)+ </rr-list> </request>

Settings submitted in request:

- service identifier;

<zone>

- zone name;

<token>

- access token

(<rr>...</rr>)+

resource records in the request should be transferred

as XML data

;

+

- one and more repetitions.

Request example:

PUT https://api.nic.ru/dns-master/services/TESTSERVICE/zones/TEST.RU/records Authorization: Bearer 123123123123 <?xml version="1.0" encoding="UTF-8" ?> <request> <rr-list> <rr> <name>@</name> <type>NS</type> <ns> <name>ns4-l2.nic.ru.</name> </ns> </rr> <rr> <name>@</name> <type>NS</type> <ns> <name>ns8-l2.nic.ru.</name> </ns> </rr> </rr-list>

(34)

</request>

If the request is successful, HTTP code 200 will be returned in the response. Request body contains created records and has the following look:

<?xml version="1.0" encoding="UTF-8" ?>

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

4.5.2 Obtaining records list in zone

Request format for records obtaining in zone:

GET https://api.nic.ru/dns-master/services/<service>/zones/<zone>/records Authorization: Bearer <token>

The second request option:

(35)

Settings submitted in request:

- service identifier;

<zone>

- zone name;

<token>

- access token

<rr_id>

- record identifier

Request example:

GET https://api.nic.ru/services/MYSERVICE/zones/TEST.RU/records?token=1223123

If the request is successful, HTTP code 200 will be returned in the response. The response body contains resource records which are already created in

the zone file and have the following look:

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

(36)

</response>

4.5.3 Deleting resource record

The request format for deleting resource record has the following look:

DELETE https://api.nic.ru/dns-master/services/<service>/zones/<zone>/records/<rr_id> Authorization: Bearer <token>

Settings submitted in request:

- service identifier;

<zone>

- zone name;

<token>

- access token

<rr_id>

- record identifier

Request example:

DELETE https://api.nic.ru/dns-master/services/MYSERVICE/zones/TEST.RU/records/210075 Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response.

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

(37)

</errors> </response>

4.6 Presentation of resource records as XML data

In adding (or editing) request body resource records should be transferred as XML data.

ttl

setting - optional setting and may be set both in numeric form and in wdhs form maintained by BIND.

If ttl setting has not been set in the request,

TTL default value will be applied.

name

setting may have value both in Punycode and in IDN.

4.6.1 SOA–record

SOA record (Start of Authority) or initial zone record indicates, which server stores reference information about this domain, contains contact details

of the person responsible for this zone, caching time parameters of zone information and interface of DNS servers.

To transfer SOA record in the request body it should be presented in the following form:

<rr> <name>name</name> <ttl>ttl</ttl> <type>SOA</type> <soa> <mname> <name>ns-name</name> </mname> <rname> <name>mail</name> </rname> <serial>serial</serial> <refresh>refresh</refresh> <retry>retry</retry> <expire>expire</expire> <minimum>minimum</minimum>

(38)

</soa> </rr>

Settings:

Name

– zone name;

ns-name

– name of primary DNS server of zone;

mail

– contact address of the person responsible for zone administration;

serial

- serial number of zone file;

refresh -

indicates how often secondary servers shall request primary server for agreement of zone description;

retry

- indicates how long the secondary name server shall wait before reattempting the primary server request for zone description agreement, if the

previous attempt failed;

expire

- indicates upper time limitation during which the secondary server may use earlier data about the zone before they expire due to loss of

update;

minimum

- minimum expectation time of negative responses to resource requests, not existing in DNS.

SOA-record represented as XML data:

(39)

4.6.2 A–record

A record (address record) or address record — connects host name with IP-address.

To transfer A record in the request body it should be presented in the following form:

Settings:

Name

- domain name, to which this resource record is linked or belongs;

IP

– IP address

A-record (

test.ru. 3600 IN A 192.168.0.1

) represented as XML data:

4.6.3 AAAA–record

AAAA record — address in IPv6 format.

To transfer AAAA record in the request body it should be presented in the following form:

(40)

Settings:

Name

- domain name, to which this resource record is linked or belongs;

Ipv6

– IPv6 address

AAAA record (

test.ru. 86400 IN AAAA 222:10:2521:1:210:4bff:fe10:d24

) represented as XML data:

4.6.4 CNAME–record

CNAME record (Canonical name) — canonic name for the alias, used for redirection to another name (single-level readressing).

To transfer CNAME record in the request body it should be presented in the following form:

<rr> <name>alias</name> <ttl>ttl</ttl> <type>CNAME</type> <cname> <name>canonical</name> </cname> </rr>

Settings:

(41)

CNAME-record (

www.test.ru. IN CNAME test.ru.

) represented as XML data:

<rr> <name>www.test.ru.</name> <type>CNAME</type> <cname> <name>test.ru.</name> </cname> </rr>

4.6.5 NS–record

NS record (name server) — node address responsible for the domain zone. To transfer NS record in the request body it should be presented in the

following form:

Settings:

name

- domain name, to which this resource record is linked or belongs;

ns-name

– name of DNS server, which is authoritative for this zone.

NS-record (

test.ru. 3600 IN NS ns3-l2.nic.ru.

) represented as XML data:

<rr>

(42)

4.6.6 MX–record

MX record (mail exchange) or mail exchanger — indicates the mail exchange server(s) for this domain. To transfer MX record in the request body it

should be presented in the following form:

<rr> <name>name</name> <ttl>ttl</ttl> <type>MX</type> <mx> <preference>priority</preference> <exchange> <name>mail-relay</name> </exchange> </mx> </rr>

Settings:

Name

- domain name, to which this resource record is linked or belongs;

priority —

priority (the higher the number is, the lower the priority is);

mail-relay —

mail gateway address for the domain

A-record (

test.ru. 86400 IN MX 10 mail.test.ru.

) represented as XML data:

<rr>

(43)

4.6.7 SRV–record

SRV record (Server selection) indicates to servers location for various services, as well as to the protocol under which this service operates. To transfer

SRV record in the request body it should be presented in the following form:

<rr> <name>service-proto</name> <ttl>ttl</ttl> <type>SRV</type> <srv> <priority>0</priority> <weight>weight</weight> <port>port</port> <target> <name>target</name> </target> </srv> </rr>

Settings:

service-proto —

name of the service and name of protocol. Service is recorded as _service name, protocols _tcp or _udp are typically used;

priority —

priority (the higher the number is, the lower the priority is);

weight —

record weight. To be used for the records with the similar priority;

port —

port on the server;

(44)

target —

canonic name of the server representing the service.

SRV-record (

_sip._tcp.test.ru. IN SRV 0 5 5060 sipserver.test.ru.

) represented as XML data:

<rr> <name>_sip._tcp.test.ru.</name> <type>SRV</type> <srv> <priority>0</priority> <weight>5</weight> <port>5060</port> <target> <name>sipserver.test.ru.</name> </target> </srv> </rr>

4.6.8 PTR–record

PTR record (Domain name pointer) or point record — serves for back conversion of IP address to host name. To transfer PTR record in the request

body it should be presented in the following form:

Settings:

(45)

host-name —

absolute host name (with the dot at the end of the name).

PTR record (

1.0.168.192.in-addr 86400 IN PTR www.test.ru.

), represented as XML data:

4.6.9 TXT–record

TXT record (Text string) contains general textual information, for example specifies the host location. To transfer TXT record in the request body it

should be presented in the following form:

Settings:

Name

- domain name, to which this resource record is linked or belongs;

text —

arbitrary binary data record, up to 255 bytes;

(46)

TXT-record (

mail.test.ru. IN TXT "Location this machine: City"

) represented as XML data:

<rr>

<txt>

<string>Location this machine: City</string> </txt>

</rr>

4.6.10 DNAME–record

DNAME record (Domain Name) — alias for the domain. Ensures redirection of the name of non-terminal domain. DNAME causes renaming of the

root and all descendents in the sub-tree of the domain name space, enables to rename part of the domain name space and connect two name spaces. To

transfer DNAME record in the request body it should be presented in the following form:

<rr> <name>name</name> <ttl>ttl</ttl> <type>DNAME</type> <dname> <name>target</name> </dname> </rr>

Settings:

Name

- domain name, to which this resource record is linked or belongs;

target

— domain name, to which redirection is made.

(47)

DNAME-record (

host.ru. 3600 IN DNAME test.ru.

) represented as XML data:

<rr> <name>host.ru.</name> <ttl>3600</ttl> <type>DNAME</type> <dname> <name>test.ru.</name> </dname> </rr>

4.6.11 HINFO–record

HINFO record (Host Information) — specifies types of the equipment and host operating system. To transfer HINFO record in the request body it

should be presented in the following form:

<rr> <name>name</name> <ttl>ttl</ttl> <type>HINFO</type> <hinfo> <hardware>cpu</hardware> <os>os</os> </hinfo> </rr>

Settings:

name —

name of the node, which hardware and software is specified in the data section for this record;

cpu —

hardware used by the node;

os —

operating system under which the node operates.

HINFO-record (

test.ru IN HINFO “PC-Intel-700mhz” “RUEL 6.0”

) represented as XML data:

<rr>

(48)

<name>test.ru.</name> <type>HINFO</type> <hinfo> <hardware>PC-Intel-700mhz</hardware> <os>RUEL 6.0</os> </hinfo> </rr>

4.6.12 NAPTR–record

NAPTR record (Naming authority pointer) — defines the rule of substitution based on a regular expression applied for the corresponding value which

will yield domain new designation or uniform resource identifier (URI). The resultant designation of the domain or URI may be used in serial requests

of NAPTR-record or as display of the whole process, for which this system is used.

To transfer NAPTR record in the request body it should be presented in the following form:

<rr> <name>name</name> <ttl>ttl</ttl> <type>NAPTR</type> <naptr> <order>order</order> <preference>preference</preference> <flags>flags</flags> <service>service</service> <regexp>regexp</regexp> <replacement> <name>replacement</name> </replacement> </naptr> </rr>

Settings:

name —

domain name to which resource record is referred to;

(49)

preference —

16-digit integer specifying the order in which lower values shall be processed earlier than higher values. If there are a few records with

the same 'Order' in the NAPTR records set, 'Preference' value should be used to solve which record is to be selected;

flags —

used to control re-recording aspects and interpretation of fields in record. Only four flags are currently defined: "S", "A", "U" and "P";

service —

defines the services accessible for path re-recording. It may also be defined by a particular private protocol that is used to exchange

messages with the service;

regexp —

substitution expression;

replacement —

for non-final NAPTR records it specifies the following domain name for the search.

SOA-record represented as XML data:

<rr> <name>test.ru.</name> <ttl>3600</type> <type>NAPTR</type> <naptr> <order>2</order> <preference>0</preference> <flags>s</flags> <service>http</service> <regexp>_sip._tcp.test.ru</regexp> <replacement> <name>.</name> </replacement> </naptr> </rr>

4.6.13 RP–record

RP record (Responsible person) contains e-mail address (in which @ is replaced by a dot) of the person responsible for the machine or domain and

TXT alias, which can be used for obtaining additional information (for example, phone number or full name).

To transfer NS record in the request body it should be presented in the following form:

(50)

<name>name</name> <ttl>ttl</ttl> <type>RP</type> <rp> <mbox-dname> <name>mbox-dname</name> </mbox-dname> <txt-dname> <name>txt-dname</name> </txt-dname> </rp> </rr>

Settings:

name

- domain name, to which this resource record is linked or belongs;

mbox-dname —

defines e-mail address;

txt-dname —

domain name for which TXT record exists

RP-record (

example.test.ru. IN RP root.example.test.ru. ops.cs.umd.ru.

) presented as XML data:

<rr> <name>example.test.ru.</name> <type>RP</type> <rp> <mbox-dname> <name>root.example.test.ru.</name> </mbox-dname> <txt-dname> <name>ops.cs.umd.ru.</name> </txt-dname> </rp> </rr>

5. Description of requests to API for DNS master services

(51)

5.1.1 Obtaining master server list

The format of the request for obtaining the master server list for Secondary has the following look:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/masters Authorization: Bearer <token>

The second request option:

GET https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/masters?token=<token>

Settings submitted in request:

<service_id>

- service identifier;

<zone_name>

- domain zone in Punycode;

<token>

- access token

Request example:

GET https://api.nic.ru/dns-master/services/TESTSERVICE/zones/TEST.RU/masters Authorization: Bearer 123123123123

If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

<?xml version="1.0" encoding="UTF-8" ?> <response> <status>success</status> <data> <address>12.12.12.12</address> <address>12.12.12.12/29</address> <address>127.0.0.1</address> </data> </response>

(52)

Settings submitted in request:

address

– IPv4 address of the master server. First more prioritized addresses are returned.

If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

</response>

5.1.2 Create list of master servers

The higher priority of the master server the earlier its IPv4 address shall be transferred in the request.

The format of the request for obtaining the list of versions has the following look:

POST https://api.nic.ru/dns-master/services/<service_id>/zones/<zone_name>/masters Authorization: Bearer <token>

<?xml version="1.0" encoding="UTF-8" ?> <request> <address>address1</address> <address>address2</address> <address>addressN</address> </request>

Settings submitted in request:

<service_id>

API of DNS hosting. For DNS-master and Secondary services Table of contents

API of DNS hosting. For DNS-master and Secondary services

Table of contents

API of DNS hosting. For DNS-master and Secondary services ... 1

1. Introduction ... 3

2. Setting access area of application for issuing token ... 4

2.1

The examples of the scope setting values for token issuance for DNS hosting services: ... 5

2.2

Examples of requests to obtain token by login and password through basic HTTP authorization ... 6

Settings submitted in request: ... 7

3. Description of general requests to API of DNS hosting ... 7

3.1

Obtaining list of DNS hosting services under agreement ... 7

Settings submitted in request: ... 8

3.2

Work with domain zones ... 8

3.2.1

Obtaining the list of all domain zones irrespective of the services they are placed under ... 9

3.2.2

Obtaining the list of all domain zones under specific service ... 9

Settings submitted in request: ... 10

3.2.3

Zone creation under the service ... 10

Settings submitted in request: ... 11

3.2.4

Domain zone creation with service auto-selection ... 12

Settings submitted in request: ... 13

3.2.5

Domain zone transfer from one DNS hosting service to another ... 14

3.2.7

Obtaining the list of addresses, from which zone XFER is permitted... 16

3.2.8

Changing the list of addresses, from which zone XFER is permitted ... 17

4. Description of requests to API for DNS master services ... 19

4.1

Working with zone files ... 19

4.1.1

Obtaining current zone file for the domain ... 19

In several errors occurred, all errors with the correspondent codes will be transferred in the response body. ... 22

4.1.2

zone file upload ... 22

4.2

Cancellation of introduced changes in zone ... 24

4.3

Working with zone versions ... 25

4.3.1

Fixing zone version and zone upload to DNS servers ... 25

4.3.2

Obtaining the list of zone versions ... 26

4.3.3

Zone version view ... 27

4.3.4

Installation of the selected zone version as the current one ... 29

4.4

$TTL value management ... 30

4.4.1

Set $TTL value ... 30

4.4.2

Obtaining current $TTL value ... 31

4.5

Working with resource records ... 32

4.5.1

Adding resource record ... 32

4.5.2

Obtaining records list in zone ... 34

4.5.3

Deleting resource record ... 36

4.6

Presentation of resource records as XML data ... 37

4.6.1

SOA–record ... 37

4.6.3

AAAA–record ... 39

4.6.4

CNAME–record ... 40

4.6.5

NS–record ... 41

4.6.6

MX–record ... 42