H-Sphere XML API Reference

• What Is H-Sphere XML API
  • Mechanism of Interaction
• Where To Get H-Sphere XML API
• How To Enable and Test H-Sphere XML API
• Services
  • Admin Services
  • User Services
  • Domain Services
  • Domain Web Services
  • FTP Services
  • DNS Services (updated in 2.5.0 beta 2)
  • Mail Services (updated in 2.5.0 beta 3)
  • MySQL Services
  • PostgreSQL Services
  • MSSQL Services
  • Support Services
  • PGP Services
  • Migration Services
  • User FTP Services ( in 2.5.0 beta 2)
• XML Message Structure
• Special Beans: AuthToken
• Error Messages (SOAP Fault)

This reference is also available in PDF format.

What Is H-Sphere XML API

H-Sphere XML API, written in Java, is designed to manage 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.

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 H-Sphere service;
• the target 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 a SOAP fault.

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

Where To Get H-Sphere XML API

You can download Axis libraries and the latest version of H-Sphere Axis-based Web services from PSoft site.

Also, you can test H-Sphere XML functionality with our sample Java classes.

How To Enable And Test H-Sphere XML API

Please read a separate document on enabling and testing H-Sphere XML API.

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
• Domain Web Services - managing Web options
• FTP Services - managing FTP
• 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 (H-Sphere support center)
• Migration Services - migrating users and resellers by means of corresponding XML forms
• PGP Services - PGP encryption/decryption in H-Sphere trouble tickets

XML Message Structure

Each XML request/response message is wrapped into a SOAP envelope:

Inside the SOAP envelope, message body is enclosed into the <soapenv:Body> tag:

Later in the H-Sphere XML API documentation, only the SOAP message body is considered.

Inside the SOAP body, operations are defined as follows:

Here:

• ns1:deleteDomain is an operation;
• xmlns:ns1="DomainServices" is its service.

Then, the operation parameters are listed:

Here:

• domain is a parameter's name;
• xsi:type="xsd:string" defines the parameter's type.

More on supported types

• xsi:nil="true" - this attribute is set to true if the parameter can take the null value.

Complex value definition:

where:

• at is a parameter's name
• href="#id0" - refers to the value of the parameter defined elsewhere in this XML body within the respective multiRef construction, with id0 as its reference identifier.

The list of parameters with reference idenfifier id0:

where:

• multiRef id="id0" - defines the list of parameters refered to as id0
• xsi:type="ns2:AuthToken" - the multiRef's Bean type

Fields are defined in the same way as the operation's parameters. multiRefs can be nested.

Special Beans: AuthToken

H-Sphere XML API includes several special Beans. AuthToken is a Bean used for authentication. It defines the following parameters: accountId (int), login (string), password (string), and role (Role).

System authentication is performed with login and password.

• If accountId == 0, the system tries to choose the user's account.
  If the user has more than one account, the system responds with the respective fault message.
• If accountId <> 0, the system tries to load the account with that accountId. If role is not empty, the system tries to drop permissions based on the values of the role parameter.

Example:

The Role parameter enables operating under a user identity different from the admin account. If the account has admin privileges, the system will try to switch to the Role user, and the accountId defined in the role tag will be regarded as the user identity. If accountId is 0, system will check if the user has only one account, and will operate under that account.

Example:

Error Messages (SOAP Fault)

A standard error response in H-Sphere XML API looks like:

Here:

• soapenv:Fault - container for the error response;
• faultcode - method where the error occured;
• faultstring - error message;
• detail - error details.