Previous page

Next page

Locate page

Print this page

Plesk API RPC Packet Structure

Plesk API RPC packet is a simple XML document included to a HTTP message body.

XML API compliant packet structure

 

Speaking of the Plesk XML-RPC packet structure, we distinguish the following parts:

  1. HTTP header – transport part. Besides other standard information, it must contain data on the server where the operation will be performed, and the login credentials of Plesk user on whose behalf the operation will be performed.
  2. XML packet header specifying the version of Plesk API RPC protocol (which is an opening tag of the XML message root element <packet>).
  3. XML packet body containing commands or the their result (all XML message elements nested within the root).

Hereinafter, we refer to XML packet header and body together as to a (XML) packet.

Here is an example of Plesk API RPC message sent to the Plesk server:

POST /enterprise/control/agent.php HTTP/1.1

Host: 10.58.83.1:8443

Accept: */*

HTTP_AUTH_LOGIN: admin

HTTP_AUTH_PASSWD: setup

Pragma: no-cache

Content-Length: 1398

Content-Type: text/xml

HTTP header

The HTTP header indicates that the HTTP method used is POST, the handling agent is located at /enterprise/control/agent.php, and the HTTP version is 1.1. The Host element specifies IP address and the port of the Plesk server to which the message is addressed. HTTP_AUTH_LOGIN and HTTP_AUTH_PASSWD elements hold Plesk Administrator's login credentials. The Content-Type must be "text/xml". The length of the passed message is also required.

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

Beginning of the XML part

<packet version="1.4.0.0">

Packet header

The version attribute specifies the required version of Plesk API RPC protocol.

<client>

<add>

   <gen_info>

       <cname>LogicSoft Ltd.</cname>

       <pname>Stephen Lowell</pname>

       <login>stevelow</login>

       <passwd>steve78</passwd>

       <status>0</status>

       <phone>416 907 9944</phone>

       <fax>928 752 3905</fax>

       <email>host@logicsoft.net</email>

       <address>105 Brisbane Road, Unit 2

       </address>

       <city>Toronto</city>

       <state/>

       <pcode/>

 

Packet body

Always starts from tag of the related operator.

This particular packet uses the client operator to create a Plesk client account. The elements nested within the gen_info node contain data necessary to register the new client in Plesk database.

The elements nested within the limits node specify the client's restrictions imposed on use of various Plesk resources.

The elements nested within the permissions node indicate the state (enabled/disabled) of various management capabilities for the new client.

E.g., the remote_access_interface node nested within permissions indicates that the client is allowed to access Plesk object via Plesk API RPC.

       <country>CA</country>

   </gen_info>

   <limits>

       <disk_space>100000</disk_space>

       <max_dom>50</max_dom>

       <max_subdom>250</max_subdom>

       <max_webapps>30</max_webapps>

       <max_traffic>50000</max_traffic>

       <max_db>200</max_db>

       <mysql_dbase_space>50000

       </mysql_dbase_space>

       <max_shared_ssl_links>50

       </max_shared_ssl_links>

       <expiration>1134616208</expiration>

   </limits>

   <permissions>

    <create_domains>true</create_domains>

    <manage_phosting>true</manage_phosting>

 

The structure of the packet body is compliant with the client_input.xsd XML schema of Plesk XML API v.1.4.0.0.

    <manage_quota>false</manage_quota>

    <manage_subdomains>true </manage_subdomains>

    <change_limits>true</change_limits>

    <manage_dns>true</manage_dns>

    <manage_log>true</manage_log>

    <manage_anonftp>true</manage_anonftp>

    <manage_webapps>true</manage_webapps>

    <manage_sh_access>true</manage_sh_access>

    <manage_maillists>true</manage_maillists>

    <make_dumps>true</make_dumps>

    <remote_access_interface>true </remote_access_interface>

    <cp_access>true</cp_access>

    <manage_domain_aliases>true </manage_domain_aliases>

   </permissions>

</add>

</client>

 

</packet>

Trailing tag closing the packet

 

In fact, Plesk API RPC supports two types of messages:

The example above shows the request message structure. Both types are similar in the structure, but HTTP headers and bodies look different. Message sent by the server in response to the request above could look as follows:

HTTP/1.1 200 OK

Connection: close

Content-Length: 161

Content-Type: text/xml

Date: Mon, 3 Jul 2006 10:55:08 GMT

Server: Plesk/800

Standard header of the HTTP server response

The MIME type is text/xml. The Server element shows that the request was handled by Plesk v.8.0.0 on the server side.

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

Standard header of a valid XML document

<packet version="1.4.0.0">

XML packet header

<client>

<add>

   <result>

       <status>ok</status>

       <id>5361</id>

   </result>

</add>

</client>

Packet body

The root node of the packet body is the client operator.

 

The nested lines indicate that the ADD operation was successfully performed. Also, the server passes back the client's ID.

 

The structure of the packet body is compliant with the client_output.xsd XML schema of Plesk XML API v.1.4.0.0.

</packet>

Trailing tag closing the packet