Retrieving DNS Records

Both zone template records and site or site alias zone records can be retrieved using the get_rec operation. You can retrieve multiple records in a single get_rec operation using filtering rules. For more information about filters, refer to the Available Filters section.

In this chapter:

Request Packet Structure

Response Packet Structure

Samples

 
Request Packet Structure

A request XML packet retrieving a DNS record from Plesk database includes the get_rec operation node:

<packet>
<dns>
   <get_rec>
   ...
   </get_rec>
</dns>
</packet>

 

The graphical representation of the get_rec node is as follows:

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • The filter node is required. It specifies the filtering rule. For more information, refer to the Available Filters section. Data type: dnsSelectionFilterType(dns_input.xsd).
  • The template node is optional. If present, only DNS zone template records are available for retrieving. In this case filter children cannot be specified as a filtering rule. Data type: none.

Note: If you leave the filter node blank (<filter/>), all resource records (zone template records or zone records depending on presence of the template node in the request packet) will be retrieved.

You can retrieve multiple DNS records in a single packet. Add as many get_rec operations as the number of different filtering rules.

<dns>
   <get_rec>
   ...
   </get_rec>
...
   <get_rec>
   ...
   </get_rec>

</dns>

Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.

 
Response Packet Structure

The get_rec node of the output XML packet is structured as follows:

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • The result node is optional. It is required if the operation get_rec succeeds, and the data set retrieved from the server is not empty. Data type: resultType (common.xsd).
  • The status node is required. It specifies the execution status of the get_rec operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. It is used to return the error code when the get_rec operation fails. Data type: unsignedInt.
  • The errtext node is optional. It is used to return the error message if the get_rec operation fails. Data type: string.
  • The id node is required if the get_rec operation has succeeded. Returns the unique identifier of the DNS record. Data type: integer.
  • The data node is optional. It is required if the get_rec operation has succeeded. Data type: dnsRecord (dns_input.xsd). The node is structured as follows:

    • The site-id node is optional. If specified, the DNS record is retrieved from zone parameters for the site with the corresponding ID. Data type: integer.
    • The site-alias-id node is optional. If specified, the DNS record is retrieved from zone parameters for the site alias with the corresponding ID. Data type: integer.
    • The type node is optional. It is required if the operation succeeded. It specifies the type of the DNS record. For more information about DNS types, please visit the Adding a DNS Record section. Data type: string. Allowed values: A | NS | CNAME | MX | PTR | TXT | SOA | AXFR | SRV | AAAA | DS.
    • The host node is optional. It is required if the operation succeeded. It specifies the IP address or name of a host, that will be used by DNS. Data type: string.
    • The value node is optional. It is required if the operation succeeded. It specifies the value that will be linked with the host value. Data type: string.
    • The opt node is optional. It holds optional information about the DNS record. Data type: string.
 
Samples
Retrieving a single DNS record

This request packet retrieves the DNS record with ID 8.

<packet>
<dns>
 <get_rec>
  <filter>
   <id>8</id>
  </filter>
 </get_rec>
</dns>
</packet>

Response:

<packet>
<dns>
 <get_rec>
  <result>     
   <status>ok</status>
    <id>8</id>
     <data>
    <site-id>8</site-id>
     <type>NS</type>
     <host>Mysite.com</host>
     <value>ns.Mysite.com</value>
     <opt></opt>
    </data>
  </result>
 </get_rec>
</dns>
</packet>  

If the DNS record with ID 8 was not found on the server, the response looks as follows:

<packet>
<dns>
  <get_rec>
  </get_rec>
</dns>
</packet>

 

Retrieving multiple DNS records

This request packet retrieves zone preferences of the site with ID 8.

<packet>
<dns>
 <get_rec>
  <filter>
   <site-id>8</site-id>
  </filter>
 </get_rec>
</dns>
</packet>

Response:

<packet></code>
<dns>
<get_rec>
<result>
   <status>ok</status>
<code>   <id>18</id>
   <data>
    <site-id>8</site-id>
    <type>NS</type>
    <host>Mysite.com</host>
    <value>ns.Mysite.com</value>
    <opt></opt>
   </data>
  </result>
 <get_rec>
  <result>
   <status>ok</status>
   <id>19</id>
   <data>
    <site-id>8</site-id>
    <type>PTR</type>
    <host></host>
    <value>Mysite.com</value>
    <opt></opt>
   </data>
  </result>
</get_rec>
</dns>
</packet>

If the site with ID 8 was not found on the server, the response from the server looks as follows:

<packet>
<dns>
   <get_rec>
   </get_rec>
</dns>
</packet> 
  <get_rec>
  <result>
   <status>ok</status>
   <id>19</id>
   <data>
    <site-id>8</site-id>
    <type>PTR</type>
    <host></host>
    <value>Mysite.com</value>
    <opt></opt>
   </data>
  </result>
</get_rec>
</dns>
</packet>

 

 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.