XML API Protocol
Plesk provides the XML-based API to support interaction with third-party software. This interface lets you manage Plesk objects - subscriptions, service plans, customer accounts, and so on. The interface is designed as a means of calling Plesk operations remotely. This ability is reflected in its name - XML API - Application Programming Interface for Remote Procedure Calls.
How to work with XML API
To perform an operation through XML API, you should send a specifically-structured HTTP message to a particular Plesk endpoint (https://<your-host-or-IP>:8443/enterprise/control/agent.php). Plesk receives the message, transforms the message to the operation instruction, attempts to perform the operation, and returns the operation status and details.
An arbitrary HTTP message, a unit of interaction between third-party software and XML API, can be represented graphically in the following way:
When forming the message, you should include Plesk user credentials as specific HTTP headers and insert an XML presentation of the operation into the HTTP body. The format of such XML presentations and the format of the XML-like responses from Plesk are covered by the XML API protocol.
From Theory to Practice
In practical terms, to perform an operation through XML API, you should do the following:
- Create an XML presentation of the operation
- Add the XML code to the body of an HTTP message
- Add Plesk user credentials to the message header (HTTP_AUTH_LOGIN and HTTP_AUTH_PASSWD)
- Send this HTTP message to the Plesk endpoint.
Below, we provide more details on each of the steps.
Create an operation description.
Construct the XML presentation using the Reference chapter of the latest version of the XML API Guide.
For example, if you wish to add a reseller plan, you should have an XML structure similar to this one:
<packet version="220.127.116.11"> <reseller-plan> <add> <name>sample_plan</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </add> </reseller-plan> </packet>
Form an HTTP message and send it to Plesk.
There are a variety of libraries that let you easily create and send HTTP messages with custom headers and body. Depending on the programming language you use, utilize cURL, HttpWebRequest, or other libraries.
Parse and analyze the Plesk response.
Plesk responds to each XML API request packet with a response packet that contains an operation status and details. For the details on structures Plesk returns for each operation, consult the Reference chapter as well. If the operation status is OK, you have successfully performed the remote operation.
Further details and instructions related to XML API are available in the XML API Guide. As we mentioned earlier, the document contains the explanation of the protocol, client software samples, and XML presentations of all operations supported by Plesk through XML API.