Validation Schemas

XML schema are used in the following two cases:

1. When a packet is created (request packet created by developer/client software, or response packet created by Plesk API RPC server)
2. When a packet is read and validated (request packet validated by Plesk server, or response packet validated by a client software)

Creating XML-RPC packets

First, let us look at how to retrieve the useful information from the XML schema when creating a packet. Assume that we have Plesk Client access permissions, and need to create a domain and remove some old ones. Assume that we know the version of Plesk installed on the server side, say, it is Plesk 8.0 for Linux/Unix. All this means that we better use version 1.4.1.0 of API RPC. The operations on domains for this version are described in the relevant domain_input.xsd schema. Its graphical representation (a cut version) correlates with the body of the XML packet as follows:

XML packet body looks as follows:

<domain>

<add>

   <gen_setup>

      <name>newdomain.com</name>

      <ip_address>123.123.123.123</ip_address>

   </gen_setup>

</add>

<del>

   <filter>

        <id>1</id>

        <id>2</id>

        <id>3</id>

   </filter>

</del>

</domain>

Here, the requested domain operations (ADD and DEL) are nested within the DOMAIN operator element. Similarly, operations on Plesk clients would require the use of the CLIENT operator, and so on. For information on which operators supported by each API RPC version, refer to the API RPC Versions section of the API RPC Reference.

Note that starting with version 1.4.0.0, Plesk API RPC supports heterogeneous requests, i.e., the requests for operations on different Plesk objects. Such a request can look as follows:

<client>

   <add>

   …

   </add>

</client>

<domain>

   <add>

   …

   </add>

</domain>

Each group of operations is isolated within the relevant operator so that operations with similar names requested for different Plesk objects would never conflict.

Validating XML-RPC packets

Let us look at how Plesk API RPC server chooses the right XML schema(s) to validate a packet just arrived.

Plesk API RPC server is arranged as a set of agents – or operators – managed by the Agent Engine. Every agent is a logical block responsible for handling a certain group of commands, and the Agent Engine serves as a packet dispatcher.

In addition, Agent Engine is associated with several sets of XML API schemas. Each set relates to a certain API RPC version supported by Plesk. An entry point to each version is the agent_input.xsd file that references all 'input' schemas of the same version.

Plesk API RPC server functions as follows. First the pure XML packet, its HTTP header peeled off, gets to Agent Engine. Agent Engine retrieves the required API RPC version from the packet header and decides which of two supported schema resolution models to apply.

Old schema resolution model

The old schema resolution algorithm is applied to incoming packets that specify API RPC version 1.3.5.1 and lower. This algorithm does not implement the validation as it is. Once Agent Engine has read the API RPC version form the packet header, the incoming packet is passed further to the relevant operator. The operator parses the packet body, forms calls to Plesk internal functions, performs these invocations, gets the result, forms the response API RPC packet, and returns it to Agent Engine.

New schema resolution model

In Plesk 8 for Linux/Unix / Plesk 7.5.6 for Windows and higher, validation takes place before the incoming packet is passed to the proper operator. The Agent Engine retrieves the API RPC version from the packet header, chooses the matching set of XML schemas, and switches to the right agent_input.xsd schema. This schema validates the operator level of the packet, after which each operator section of the packet is validated with the proper subsequent schema.

If the packet is considered invalid, Agent Engine forms an error report and sends it back to the client. If all elements of the packet are validated successfully, Agent Engine checks whether it has all agent modules necessary for further processing and invokes them one after another.

Each agent (operator) invoked receives its operator packet section, parses it, forms calls to internal functions, and returns the result of the executed commands to Agent Engine.