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

Transcription

1 API of DNS hosting. For DNS-master and Secondary services Table of contents API of DNS hosting. For DNS-master and Secondary services Introduction Setting access area of application for issuing token The examples of the scope setting values for token issuance for DNS hosting services: Examples of requests to obtain token by login and password through basic HTTP authorization... 6 Settings submitted in request: Description of general requests to API of DNS hosting Obtaining list of DNS hosting services under agreement... 7 Settings submitted in request: Work with domain zones Obtaining the list of all domain zones irrespective of the services they are placed under Obtaining the list of all domain zones under specific service... 9 Settings submitted in request: Zone creation under the service Settings submitted in request: Domain zone creation with service auto-selection Settings submitted in request: Domain zone transfer from one DNS hosting service to another Domain zone deletion from the service... 15

2 3.2.7 Obtaining the list of addresses, from which zone XFER is permitted Changing the list of addresses, from which zone XFER is permitted Description of requests to API for DNS master services Working with zone files Obtaining current zone file for the domain In several errors occurred, all errors with the correspondent codes will be transferred in the response body zone file upload Cancellation of introduced changes in zone Working with zone versions Fixing zone version and zone upload to DNS servers Obtaining the list of zone versions Zone version view Installation of the selected zone version as the current one $TTL value management Set $TTL value Obtaining current $TTL value Working with resource records Adding resource record Obtaining records list in zone Deleting resource record Presentation of resource records as XML data SOA record A record... 39

3 4.6.3 AAAA record CNAME record NS record MX record SRV record PTR record TXT record DNAME record HINFO record NAPTR record RP record Description of requests to API for DNS master services Master Server List Management Obtaining master server list Create list of master servers 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 (<method>) specifying access rights to the set scope and <url path>, specifying the access area are colon-separated. Setting <method> 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 <url path> is set by regular expression}with the limitation set for characters ^ and $ without specification of the domain and protocol ( 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 <service>; /dns-master/services/<service>/zones/<zone>(/.+)? for granting access to particular zone <zone> on particular service <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 <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 <service>. List items in scope setting (PUT:/dns-master/services/<service>/zones/<zone1>(/.+)? and POST:/dnsmaster/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 <service>; scope=get:/dns-master/services/<service>/.+ only data read limitation for service <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 <service1>, 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 <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 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 HTTP/1.1 Authorization: Basic czzcagrsa3f0mzpnwdfmqmf0m2jw Content-Type: application/x-www-form-urlencoded grant_type=password&username=123/nic-reg&password=qwerty&scope=get%3a%2fdns-master%2f.%2b

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 <service>: POST 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 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 The second request option: GET 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: <status>success</status> <data> <service admin="123/nic-reg" domains-limit="12" domains-num="5" enable="true" has-primary="false" name="testservice" payer="123/nic-reg" tariff="secondary L" /> <service admin="123/nic-reg" domains-limit="150" domains-num="10" enable="true" has-primary="true" name="myservice" payer="123/nic-reg" rr-limit="7500" rr-num="1000" tariff="dns-master XXL" /> </data> 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 3.2 Work with domain zones

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 Authorization: Bearer <token> The second request option: GET 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 Authorization: Bearer <token> The second request option: GET Settings submitted in request: <service> - service identifier under which list of domain zones should be obtained. Request example: GET Authorization: Bearer If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

10 <status>success</status> <data> <zone admin="123/nic-reg" enable="true" has-changes="false" has-primary="true" id="227645" idn-name="тест.рф" name="xn e1aybc.xn--p1ai" payer="123/nic-reg" service="myservice" /> <zone admin="123/nic-reg" enable="true" has-changes="false" has-primary="true" id="227642" idn-name="example.ru" name="example.ru" payer="123/nic-reg" service="myservice" /> <zone admin="123/nic-reg" enable="true" has-changes="false" has-primary="true" id="227643" idn-name="test.su" name="test.su" payer="123/nic-reg" service="myservice" /> </data> 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; has-primary="false" Secondary service Zone creation under the service The format of request for domain zone placement under specific service has the following look: PUT 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 Authorization: Bearer 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> <zone admin="123/nic-reg" enable="true" has-changes="false" has-primary="true" id="235640" idn-name="test.ru" name="test.ru" payer="123/nic-reg" service="myservice" /> </data> Settings submitted in request: admin agreement number; id - numeric zone identifier; idn-name IDN of zone; name zone name in Punycode; service service identifier; has-changes="true" zone has changes unloaded to DNS servers; has-changes="true" 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; has-primary="false" 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: <status>fail</satus> <errors> <error code="code">error text</error> </errors> <data/> 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 Authorization: Bearer <token> The format of request for domain zone creation with Secondary service auto-selection has the following look: PUT Authorization: Bearer <token> Settings submitted in request: <zone_name> - domain zone in Punycode;

13 <token> - access token Request example: PUT Authorization: Bearer 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> <zone admin="123/nic-reg" enable="true" has-changes="false" has-primary="true" id="235640" idn-name="mydomain.ru" name="mydomain.ru" payer="123/nic-reg" service="myservice" /> </data> Settings submitted in request: admin agreement number; id - numeric zone identifier; idn-name IDN of zone; name zone name in Punycode; service service identifier; has-changes="true" the zone has changes unloaded to DNS servers; has-changes="true" 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; has-primary="false" Secondary 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: <status>fail</satus> <errors> <error code="code">error text</error> </errors> <data/> 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 Authorization: Bearer <token> Settings submitted in request: <service> - 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 Authorization: Bearer If the request is successful, HTTP code 200 will be returned in the response.

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: <status>fail</satus> <errors> <error code="code">error text</error> </errors> <data/> Domain zone deletion from the service The format of the request for domain zone deletion has the following look: DELETE Authorization: Bearer <token> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: DELETE Authorization: Bearer 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: <status>fail</satus> <errors> <error code="code">error text</error> </errors> <data/> 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 Authorization: Bearer <token> The second request option: GET Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: GET Authorization: Bearer If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

17 <status>success</status> <data> <address> </address> <address> /29</address> <address> </address> </data> Value "any" may be specified instead of the address, when the response body will have the following look: <status>success</status> <data> <address>any</address> </data> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 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 Authorization: Bearer <token>

18 <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 Authorization: Bearer <request> <address> </address> <address> /29</address> <address> </address> </request> The second request option: POST Authorization: Bearer <request> <address>any</address> </request> If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look:

19 <status>success</status> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 4. Description of requests to API for DNS master services 4.1 Working with zone files 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 Authorization: Bearer <token> The second request option: GET Settings submitted in request:

20 <service> - service identifier; <zone> - domain zone name; <token> - access token Request example: GET Authorization: Bearer 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/ OK x-request-id: @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. ( ; serial ; refresh 3600 ; retry ; expire 600) $ORIGIN 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 MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU. $ORIGIN TXT "v=spf1 redirect=nicmail.ru" MAIL TXT "v=spf1 A MAIL A A MAIL A A MAIL A A MAIL A A MAIL A A MAIL A test DNAME 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: <status>fail</status> <errors> <error code="code">error text</error> </errors> <data/>

22 In several errors occurred, all errors with the correspondent codes will be transferred in the response body zone file upload The request body shall contain zone file contents. The format of the zone file upload request has the following look: POST Authorization: Bearer <token> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: POST Accept-Charset: UTF-8 Accept-Language: en Authorization: Bearer Content-Type: text/plain; charset=utf-8 $TTL 3600 $ORIGIN RU. MYDOMAIN 3600 IN SOA ns3-l2.nic.ru. support.nic.ru. ( ; serial ; refresh 3600 ; retry ; expire 600) $ORIGIN 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 MX 10 MX01.NICMAIL.RU. MX 5 MX02.NICMAIL.RU. MX 20 MX03.NICMAIL.RU. $ORIGIN TXT "v=spf1 redirect=nicmail.ru" MAIL TXT "v=spf1 A MAIL A A MAIL A A MAIL A A MAIL A A MAIL A A MAIL A mydomain DNAME 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/> 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 <status>fail</satus> <errors> <error code="code">error text</error> </errors> <data/> 4.2 Cancellation of introduced changes in zone The format of the request for cancellation of the introduced changes has the following look: POST Authorization: Bearer <token> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: POST Authorization: Bearer In case of a success HTTP 200 will be returned. The response body has the following look: <status>success</status> 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 <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 4.3 Working with zone versions 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 Authorization: Bearer <token> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: POST Authorization: Bearer If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look: <status>success</status> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look:

26 <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> Obtaining the list of zone versions The format of the request for obtaining the list of versions has the following look: GET Authorization: Bearer <token> The second request option: GET Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: GET Authorization: Bearer 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>

27 <revision date=" :36:57" ip=" " number="3" /> <revision date=" :36:57" ip=" " number="2" /> <revision date=" :36:56" ip="no data" number="1" /> </data> 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: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> Zone version view The request format for version view has the following look: GET Authorization: Bearer <token> The second request option: GET Settings submitted in request:

28 <service_id> - service identifier; <zone_name> - domain zone in Punycode; <revision> - version number; <token> - access token Request example: GET Authorization: Bearer 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/ OK x-request-id: @dns Connection: close Transfer-Encoding: chunked Content-Type: text/plain; charset=utf-8 $TTL 3600 $ORIGIN test.ru. test.ru IN SOA ns3-l2.nic.ru. saatchiceo.test.ru. ( ; serial 7200 ; refresh 3600 ; retry ; 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 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: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 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 Authorization: Bearer <token> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <revision> - version number; <token> - access token Request example: PUT Authorization: Bearer If the request is successful, HTTP code 200 will be returned in the response. Request body contains zone file and has the following look:

30 <status>success</status> If any errors occurred, HTTP with the error code will be transferred in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 4.4 $TTL value management Set $TTL value Default TTL = To set own $TTL value, request should be transferred. POST Authorization: Bearer <token> <request><default-ttl>ttl</default-ttl></request> Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token ttl - TTL value Request example:

31 POST Authorization: Bearer <request><default-ttl>86400</default-ttl></request> If the request is successful, HTTP code 200 will be returned in the response. The response body has the following look: <status>success</status> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> Obtaining current $TTL value The format of the request for obtaining the current TTL value has the following look: GET Authorization: Bearer <token> The second request option: GET Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode;

32 <token> - access token Request example: GET /default-ttl Authorization: Bearer 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> <default-ttl>3600</default-ttl> </data> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 4.5 Working with resource records Adding resource record The format of the request for adding resource record has the following look: PUT Authorization: Bearer <token>

33 <request> <rr-list> (...)+ </rr-list> </request> Settings submitted in request: <service> - service identifier; <zone> - zone name; <token> - access token (...)+resource records in the request should be transferred as XML data ; + - one and more repetitions. Request example: PUT Authorization: Bearer <request> <rr-list> <name>@</name> <type>ns</type> <ns> <name>ns4-l2.nic.ru.</name> </ns> <name>@</name> <type>ns</type> <ns> <name>ns8-l2.nic.ru.</name> </ns> </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: <status>success</status> <data> <zone admin="123/nic-reg" has-changes="true" id="228095" idn-name="test.ru" name="test.ru" service="testservice"> <rr l2.nic.ru.</idn-name></ns> <rr l2.nic.ru.</idn-name></ns> </zone> </data> If any errors occurred, HTTP with the error code will be returned in the response and the response body will have the following look: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> Obtaining records list in zone Request format for records obtaining in zone: GET Authorization: Bearer <token> The second request option: GET

35 Settings submitted in request: <service> - service identifier; <zone> - zone name; <token> - access token <rr_id> - record identifier Request example: GET 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: <status>success</status> <data> <zone admin="123/nic-reg" has-changes="true" id="228095" idn-name="test.ru" name="test.ru" service="myservice"> <rr id="210074"><name>@</name><idn-name>@</idn-name><type>soa</type><soa><mname><name>ns3-l2.nic.ru.</name><idnname>ns3-l2.nic.ru.</idn-name></mname><rname><name>dns.nic.ru.</name><idn-name>dns.nic.ru.</idnname></rname><serial> </serial><refresh>1440</refresh><retry>3600</retry><expire> </expire><minimum>600</m inimum></soa> <rr id="210075"><name>@</name><idn-name>@</idn-name><type>ns</type><ns><name>ns3-l2.nic.ru.</name><idn-name>ns3- l2.nic.ru.</idn-name></ns> <rr id="210076"><name>@</name><idn-name>@</idn-name><type>ns</type><ns><name>ns4-l2.nic.ru.</name><idn-name>ns4- l2.nic.ru.</idn-name></ns> <rr id="210077"><name>@</name><idn-name>@</idn-name><type>ns</type><ns><name>ns8-l2.nic.ru.</name><idn-name>ns8- l2.nic.ru.</idn-name></ns> </zone> </data> 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 <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> Deleting resource record The request format for deleting resource record has the following look: DELETE Authorization: Bearer <token> Settings submitted in request: <service> - service identifier; <zone> - zone name; <token> - access token <rr_id> - record identifier Request example: DELETE Authorization: Bearer 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: <status>fail</status> <errors> <error code="4097">access token expired or not found</error>

37 </errors> 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 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: <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> 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: <name>test.ru.</name> <type>soa</type> <soa> <mname> <name>ns3-l2.nic.ru.</name> </mname> <rname> <name>mail.test.ru.</name> </rname> <serial> </serial> <refresh>14400</refresh> <retry>3600</retry> <expire> </expire> <minimum>600</minimum> </soa>

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: <name>name</name> <ttl>ttl</ttl> <type>a</type> <a>ip</a> Settings: Name - domain name, to which this resource record is linked or belongs; IP IP address A-record (test.ru IN A ) represented as XML data: <name>test.ru.</name> <ttl>3600</ttl> <type>a</type> <a> </a> 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 <name>name</name> <ttl>ttl</ttl> <type>aaaa</type> <aaaa>ipv6</aaaa> Settings: Name - domain name, to which this resource record is linked or belongs; Ipv6 IPv6 address AAAA record (test.ru IN AAAA 222:10:2521:1:210:4bff:fe10:d24) represented as XML data: <name>test.ru.</name> <ttl>86400</ttl> <type>aaaa</type> <aaaa>222:10:2521:1:210:4bff:fe10:d24</aaaa> 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: <name>alias</name> <ttl>ttl</ttl> <type>cname</type> <cname> <name>canonical</name> </cname> Settings:

41 CNAME-record ( IN CNAME test.ru.) represented as XML data: <name> <type>cname</type> <cname> <name>test.ru.</name> </cname> 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: <name>name</name> <ttl>ttl</ttl> <type>ns</type> <ns> <name>ns-name</name> </ns> 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 IN NS ns3-l2.nic.ru.) represented as XML data: <name>test.ru.</name>

42 <ttl>3600</ttl> <type>ns</type> <ns> <name>ns3-l2.nic.ru.</name> </ns> 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: <name>name</name> <ttl>ttl</ttl> <type>mx</type> <mx> <preference>priority</preference> <exchange> <name>mail-relay</name> </exchange> </mx> 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 IN MX 10 mail.test.ru.) represented as XML data: <name>test.ru.</name> <ttl>86400</ttl>

43 <type>mx</type> <mx> <preference>10</preference> <exchange> <name>mail.test.ru.</name> </exchange> </mx> 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: <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> 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 sipserver.test.ru.) represented as XML data: <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> 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: <name>name</name> <ttl>ttl</ttl> <type>ptr</type> <ptr> <name>host-name</name> </ptr> Settings: Name - domain name, to which this resource record is linked or belongs;

45 host-name absolute host name (with the dot at the end of the name). PTR record ( in-addr IN PTR represented as XML data: <name> in-addr</name> <ttl>86400</ttl> <type>ptr</type> <ptr> <name> </ptr> 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: <name>name</name> <ttl>ttl</ttl> <type>txt</type> <txt> (<string>text</string>)+ </txt> Settings: Name - domain name, to which this resource record is linked or belongs; text arbitrary binary data record, up to 255 bytes; + - one and more repetitions.

46 TXT-record (mail.test.ru. IN TXT "Location this machine: City") represented as XML data: <name>mail.test.ru.</name> <type>txt</type> <txt> <string>location this machine: City</string> </txt> 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: <name>name</name> <ttl>ttl</ttl> <type>dname</type> <dname> <name>target</name> </dname> 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 IN DNAME test.ru.) represented as XML data: <name>host.ru.</name> <ttl>3600</ttl> <type>dname</type> <dname> <name>test.ru.</name> </dname> 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: <name>name</name> <ttl>ttl</ttl> <type>hinfo</type> <hinfo> <hardware>cpu</hardware> <os>os</os> </hinfo> 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:

48 <name>test.ru.</name> <type>hinfo</type> <hinfo> <hardware>pc-intel-700mhz</hardware> <os>ruel 6.0</os> </hinfo> 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: <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> Settings: name domain name to which resource record is referred to; order 16-digit integer, clearly setting the procedure, in which NAPTR records shall be processed to ensure correct ordering of the result;

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: <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> RP record RP record (Responsible person) contains address (in 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> Settings: name - domain name, to which this resource record is linked or belongs; mbox-dname defines 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: <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> 5. Description of requests to API for DNS master services 5.1 Master Server List Management

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 Authorization: Bearer <token> The second request option: GET Settings submitted in request: <service_id> - service identifier; <zone_name> - domain zone in Punycode; <token> - access token Request example: GET Authorization: Bearer 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> <address> </address> <address> /29</address> <address> </address> </data> The response body transfer the amount of IP addresses corresponding to the number of master servers set for the domain zone.

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: <status>fail</status> <errors> <error code="4097">access token expired or not found</error> </errors> 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 Authorization: Bearer <token> <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;