XML API

Extensions can obtain complete information and control over Plesk entities (customer accounts, service plans, and so on) via the XML API interface. This interface assumes exchanging operation requests wrapped into XML-structured packets. Plesk receives such an XML-structured operation request, processes it, and responds with a PHP class which fields mimic the XML tree structure. The structure of the XML packets is defined by the XML API protocol.

Every Plesk server supports a number of versions of XML API (for backward compatibility). It is possible send packets of a particular XML API version by explicitly providing the protocol version. If you do not specify the version, the most recent supported XML API version will be used.

Usage Examples

To perform an operation via XML API, run the call method of the pm_ApiRpc class.

$request = <<<APICALL
<webspace>
  <get>
    <filter>
      <id>170</id>
    </filter>
    <dataset>
      <gen_info/>
    </dataset>
  </get>
</webspace>
APICALL;
   
$response = pm_ApiRpc::getService('1.6.3.3')->call($request);
echo 'Domain name: ' . $response->webspace->get->result->data->gen_info->name;

Here is an example of an XML API call with an unspecified protocol version.

$request = '<server><get><stat/></get></server>';
$stats = pm_ApiRpc::getService()->call($request)->server->get->result->stat->objects;

Often, when connected as a user without administrator's privileges, you need to perform actions that require administrator's rights. In this case, use the $login argument of the call method.

For example, let's look at an extension that turns on PHP settings for a subscription. The extension sends the following request:

$request = <<<APICALL
<webspace>
  <set>
    <filter>
      <id>2</id>
    </filter>
    <values>
      <php-settings>
        <setting>
          <name>extension</name>
          <value>msql.so</value>
        </setting>
      </php-settings>
    </values>
  </set>
</webspace>
APICALL;

To perform this request, you need administrator's rights:

$response = pm_ApiRpc::getService()->call($request, 'admin');

Error Handling

If you run an XML API call with data which is not a valid XML tree, a PHP warning will be generated.

If an XML packet is not a valid operation call, the system will throw the PleskAPIParseException exception.

Additional Information

For more information about XML API, refer to the Plesk XML API Guide.