Expand API Overview

Expand provides API to perform operations on its resources. These resources include Expand, Plesk, and Virtuozzo manageable objects. In Expand API, each such object is mapped to a specific XML schema that identifies properties and operations assigned to the object. To perform an operation on a specific object, an application that utilizes the API must create an XML message formed according to a certain XML schema, and send it to Expand. The latter receives the XML message, performs the operation, and responses with an XML message containing the operation details. Thus, Expand API is a client-server interface: The server part (hereinafter called server) is the Expand server; the client part (hereinafter called client application or simply client) is a third-party application that access Expand resources via the API.

As mentioned, interaction between the server and clients implies exchanging XML messages. We will refer to each such message as to a packet. A packet issued by a client we will call request packet. A packet issued by the server we will call response packet.

Packets are transported between clients and the server in two different ways:

• Remotely via HTTPS. A client wraps a request packet into an HTTP request message-body and sends it to the Expand external endpoint. In this case, the response packet is wrapped into the HTTP response message-body.
• Locally via CLI. Expand provides a set of command line utilities called operators that process request packets. If a client has access to operators, it can perform a specific operation by running an appropriate operator. Operation parameters defined in a packet are read by the operator from STDIN. The response packet is sent to STDOUT.

Note: To prevent unauthorized access to Expand API, a client must be authorized as Expand Administrator. If a client uses CLI, Administrator's credentials are not verified (it is supposed that only Expand Administrator has access to operators). Otherwise, a client must provide Administrator's credentials in a HTTP header.

If a client uses CLI, it can alternately invoke operations by running operators with command line options. These options are called request statements - data in specific format that describes an operation to be performed. In this case, the response packet is sent to STDOUT too.
 

Both request statements and request packets are called request messages. A single request message can be processed only by a particular operator. The syntax and semantics of request messages and response packets are defined by the Expand API Protocol hereafter called simply Protocol. For details on the Protocol, refer to the Expand API Protocol Reference section of the Expand API Reference document. For details on how to create a valid request message, refer to the next chapter.