Parallels H-Sphere XML API

Parallels H-Sphere XML API, written in Java, is designed to manage Parallels H-Sphere services from remote applications via SOAP. It uses the Apache Axis implementation of SOAP and runs under the Apache Tomcat engine.

Remote applications interact with CP services by means of XML-formatted requests transferred via HTTP (direct TCP connection can also be set up). Error messages are also processed in XML.

XML schema is based on the SOAP RPC convention: http://www.w3.org/TR/soap12/.

Mechanism of Interaction

XML API provides the following mechanism of communication between remote applications and the Control Panel:

• A remote Java application calls CP methods to perform particular actions (for example, to create an account or to return the list of domains). For this, it invokes its SOAP client to form the corresponding XML request and to http it to the Control Panel;
• the CP SOAP server receives this XML request, parses the request> and calls a target Parallels H-Sphere service;
• the target Parallels H-Sphere service performs actions according to the received request (for example, creates an account or returns the list of domains), and responds via the SOAP server to the remote application.
  If the request is incorrect, the SOAP server returns XML with SOAP fault.

Therefore, though HTTP is used for data transfer, Parallels H-Sphere XML API services are not called from a Web browser!

Where To Get Parallels H-Sphere XML API

For Java, you may download Parallels H-Sphere XML API from psoft.net:

• Axis libraries: http://hsphere.parallels/shiv/HS/xml-api/Libraries.tgz
• Parallels H-Sphere Java XML API library: http://hsphere.parallels.com/shiv/HS/xml-api/hsphereXMLApi.jar
• Sample Java classes for testing Parallels H-Sphere XML API functionality: http://hsphere.parallels.com/shiv/HS/xml-api/AxisExamples.tgz

For other programming languages (for Java as well), you can use WSDL file to implement Parallels H-Sphere XML API services in this language. See how to generate WSDL via Axis.

Here you may find a sample Parallels H-Sphere signup form written in PHP 5 (which has an embedded SOAP client) using Parallels H-Sphere XML API: http://hsphere.parallels.com/HSdocumentation/xmls/xml-api/hs_xml_api_signup_example.tgz.

Services

Actions supported by XML API are grouped by services:

• Admin Services - basic admin services: adding new accounts, etc.
• User Services - basic user services: getting account information
• Domain Services - creating/deleting domains and subdomains
• Web Services - managing Web options
• FTP Services - managing FTP options
• User FTP Services - managing user FTP resources: subusers, passwors, etc.
• DNS Services - managing DNS
• Mail Services - creating/deleting mailboxes, mailing lists, autoresponders, mail forwards, etc.
• MySQL Services - managing MySQL databases and users
• PostgreSQL Services - managing PostgreSQL databases and users
• MSSQL Services - managing MSSQL databases and users
• Support Services - managing trouble tickets (Parallels H-Sphere support center)
• Migration Services - migrating users and resellers by means of corresponding XML forms
• PGP Services - PGP encryption/decryption in Parallels H-Sphere trouble tickets

See the XML API services documentation generated by the Javadoc tool: http://hsphere.parallels.com/HSdocumentation/xmls/xml-api/.

Note: When generating AuthToken for reseller, in addition to defining reseller's accountID, login and password, set also login in the Role to "" (empty) and account id in the Role to "0".