Parsing Response Packets
You can use any HTTP/FTP client library to transfer the request to Plesk and to get the result. In the common case, the resulting packet will be structured as described in the Packet Structure section. The structure of the response packet is defined by XML schemas of the XML API version you use.
packet is a root node of every response XML packet, the version attribute returns the version of Plesk XML API protocol running on the server.
A response packet contains either response of particular operators, or the Plesk application error returned in the system node. For the detailed information on the system and output nodes meanings, refer to the Handling Errors section.
To examine the structure of the response for a certain operation, you need the XML schema of the relevant operator. This schema can be detected by name, e.g., the
ip_output.xsd file name indicates that the file describes the outgoing packet structure of the ip operator. Check the schemas table to find the information about a certain operator. Alternatively, you can find the response packet structure in the corresponding section of an operator. For example, the response packet of adding an IP address can be found in Reference > Managing IP Addresses > Adding IP Address > Response Packet Structure.
Within each [operator] element of a response packet, a typical response data type contains one or more result elements. This element is represented by a complex type that typically includes type resultType defined in the
common.xsd schema as follows:
<xs:complexType name="resultType"> <xs:sequence> <xs:element name="status" type="result_status"></xs:element> <xs:element name="errcode" type="unsignedInt" minOccurs="0"></xs:element> <xs:element name="errtext" type="xs:string" minOccurs="0"></xs:element> </xs:sequence> </xs:complexType>
The result element can also contain optional nested elements if any defined in the complex type.
In common case, the format of the packet returned by the server looks as follows:
<?xml="1.0" encoding="UTF-8" ?> <packet> <[operator]> <[operation]> <result> ... </result> [ <result> ... </result> ... <result> ... </result> ] </[operation]> </[operator]> </packet>
Here, the [operator] stands for the operator used in the request packet, and the [operation] means the operation performed. The result element is always used to isolate the requested information and the execution status of the performed operation. The result section always contains the status element that contains the execution status of the performed operation.
Note: A real response packet can contain more than one operation within the operator section if the input packet requested for more multiple operations. Also, a response packet can contain more than one operator section if the input packet required for operations on multiple Plesk objects.
XML API supports filtering. Filtering is the way the request packet indicates the object to which an operation will be applied. The request packet filters objects using a special <filter> section. Parameters nested in the filter node are called filtering rule. If an operation supports filtering, it can have multiple result nodes depending on the filtering rule. The operation response packet will contain as many result nodes as many different objects were matched by the filtering rule.