Enabling H-Sphere XML API

• Enabling H-Sphere XML API
• Testing XML API
• Getting The List of Services
• Generating WSDL

H-Sphere XML API is designed to manage H-Sphere services via SOAP protocol. It is based on Apache Axis implementation of SOAP and runs under Apache Tomcat engine.

You can download Axis libraries and the latest version of XML API libraries from PSoft site.

Enabling XML API

To enable XML API in H-Sphere:

1. Log into the CP server as the cpanel user.

2. H-Sphere 2.4.3 Patch 11 and up: Edit the ~cpanel/shiva/psoft_config/allow_access.properties file to grant access to CP server via SOAP port from external IPs.

   [-] SOAP access in earlier H-Sphere versions

   Important: In H-Sphere before 2.4.3 Patch 11 SOAP access to CP server via standard 8080 port was provided by default.
   The following procedure explains how to configure SOAP access via port 8180 and should not be performed in H-Sphere 2.4.3 Patch 11 and up!

   1. Copy the wsdd config file:
      cp ~cpanel/shiva/psoft/hsphere/axis/server-config.wsdd ~cpanel/hsphere/WEB-INF/
      Skip this step if the file is already in the target location.
   2. Edit the Tomcat XML configuration file:
      
      vi ~cpanel/jakarta/conf/server.xml
   3. Find the following commented fragment:

      <!--Connector port="8080"
                  maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                  enableLookups="false" redirectPort="8443" acceptCount="100"
                  debug="0" connectionTimeout="20000"
                  disableUploadTimeout="true" /-->
      

      and replace it with the following code:

      <Connector port="8180"
              maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
              enableLookups="false" acceptCount="100"
              debug="0" connectionTimeout="20000"
              disableUploadTimeout="true" />
      

      Optionally, leave the port at 8080.

3. Restart H-Sphere.

After that, XML API will be available. You may wish to test if it works correctly by means of our test Java classes that use H-Sphere XML API.

Testing HS XML API

1. Make sure you are logged into the CP server as the cpanel user.
2. Download the latest version of test Java classes from PSoft site to the ~cpanel/shiva/psoft/hsphere/axis/test directory (create it first if it does not exist):
   
   cd ~cpanel/shiva/psoft/hsphere/axis/test/
   wget http://www.psoft.net/shiv/HS/xml-api/AxisExamples.tgz

   Note: AxisExamples.tgz is for the latest H-Sphere 3.0 version. For H-Sphere 2.5, download AxisExamples_25.tgz.

3. Extract the archive with the command:
   
   tar zxf AxisExamples.tgz
   Java source .java files will be added into the current ~cpanel/shiva/psoft/hsphere/axis/test/ directory.


4. Edit the necessary test classes (at least AdminServicesTest.java) replacing URL in the folowing line:
   
   String endpoint = "http://localhost:8080/psoft/servlet/AdminServices.jws";
   with your URL:
   String endpoint = "http://your_cp_host:8180/your_cp_url_path/AdminServices.jws";
   where your_cp_url_path is by default psoft/servlet but you may change it in your Tomcat configuration.
   If you have enabled XML API with port 8180, make sure it is specified in the URL.

Note: don't forget to include XML API libraries into your java classpass



5. Compile Java classes:
   cd ~cpanel/shiva/psoft/hsphere/axis/test/
   javac *.java
6. Upon the successful compilation, run the following command:
   
   java psoft.hsphere.axis.test.AdminServicesTest admin <hs_admin_password>
7. You will see the > prompt. Here, enter the line:
   
   searchbydomainname domain-name
   where domain-name is a customer's domain name.
8. On the next > invitation, press Enter to force the service to run.
9. Repeat the previous two steps testing other services, for instance getAccounts, getDomains, searchbydomainname, etc:
   
   [cpanel@exampleuser test]$ java psoft.hsphere.axis.test.AdminServicesTest admin admin
   >getAccounts example.com
   >Params:1:example.com
   1
   
   >getDomains example.com
   >Params:1:example.com
   no domains
   
   See in H-Sphere XML API Reference to learn how to invoke other Web services via XML interface.
10. Press CTRL-D to stop.

Getting the List of Available Services

You may get the list of available XML services by typing in your browser:

If this doesn't work, check servlet mapping in your Tomcat configuration:

1. As the cpanel user, open the ~cpanel/hsphere/WEB-INF/web.xml file for edition:
   
   vi ~cpanel/shiva/psoft/hsphere/WEB-INF/web.xml
2. Make sure the following lines are present in the file:
   
   <servlet>
   <servlet-name>AxisServlet</servlet-name>
   <display-name>Apache-Axis Servlet</display-name>
   <servlet-class>
   org.apache.axis.transport.http.AxisServlet
   </servlet-class>
   </servlet>
   
3. Find the following mapping block:
   
   <servlet-mapping>
   <servlet-name>AxisServlet</servlet-name>
   <url-pattern>*.jws</url-pattern>
   </servlet-mapping>
   
   and add the following lines right underneath:
   
   <servlet-mapping>
   <servlet-name>AxisServlet</servlet-name>
   <url-pattern>/AxisServlet</url-pattern>
   </servlet-mapping>
   
4. Restart H-Sphere


5. Try again this URL in your browser:
   
   http://your_cp_host:8180/your_cp_url_path/AxisServlet

You may also wish to test AxisTestServlet from the package of test Java classes:

Generating WSDL

You can generate WSDL files for H-Sphere XML API services by means of the Axis' org.apache.axis.wsdl.Java2WSDL utility.

For example, to generate a WSDL file for SupportServices, log into CP server as cpanel and run:

Example: H-Sphere XML API signup form implementation in PHP 5 (SOAP client embedded) via WSDL.