Interspire Shopping Cart contains an XML based installation API that can be used by web hosting companies, partners or ISPs to perform remote installations of Interspire Shopping Cart. This guide explains how to access and perform installations via the remote XML API.

Contents

  1. Introduction
  2. Creating the Request
  3. A Successful Installation Response
  4. An Erroneous Installation Response
  5. Appendix 1: Error Codes

Introduction

Interspire Shopping Cart contains an XML based API that can be used for remote installation. By passing an XML based request to a remote location, Interspire Shopping Cart will initialise and complete the installation request.

The remote installation API is useful for web hosting providers or ISPs to leverage for quick deployment of Interspire Shopping Cart on to remote systems. It assumes that all of the files from the Interspire Shopping Cart release have already been uploaded to the remote server and the necessary file/folder permissions have been set.

Creating the Request

To remotely install a copy of Interspire Shopping Cart, the files need to already exist on the remote server. The copy of Interspire Shopping Cart should not be installed (and when you visit it in your web browser, it should show you the “Interspire Shopping Cart Installation Wizard”)

To submit an XML based API request to install Interspire Shopping Cart, you must:

  • Send a Content-type/Accept header of “application/xml” to http://location.of.the.shop/admin/
  • Send the details outlined below as the HTTP POST body in a properly formatted XML feed

XML Reference

  • request – The root node of the XML document. Outlining that you wish to perform a request
    • install
      • (Required) licenseKey - A valid license key for this copy of Interspire Shopping Cart
      • (Required) shopPath – The URL that the shop will be accessible from
      • sampleData – Send this node if you wish to install the sample product data. Values are true, or 1
    • user
      • (Required) email – The email address of the store owner
      • (Required) password – The password to assign the initial store administrator account.
    • database
      • (Required) dbUser – The name of the MySQL database user
      • (Required) dbPass – The MySQL database password for the above user
      • (Required) dbDatabase – The name of the MySQL database to install the shopping cart in to
      • (Required) dbServer – The hostname of the MySQL database server to install on
      • tablePrefix – The prefix to be added to the beginning of all created database tables
      • sendStats – Include this node and set the value to true or 1 to send anonymous statistics about the remote server back to Interspire

Sample XML Request

<request>
	<install>
		<licenseKey>[LICENSE KEY]</licenseKey>
		<shopPath>http://www.example.com/store</shopPath>
		<sampleData>true</sampleData>
		<user>
			<email>administrator@example.com</email>
			<password>password</password>
		</user>
		<database>
			<dbUser>root</dbUser>
			<dbPass></dbPass>
			<dbDatabase>example_store</dbDatabase>
			<dbServer>localhost</dbServer>
			<tablePrefix>true</tablePrefix>
		</database>
		<sendStats>true</sendStats>
	</install>
</request>

Sample PHP Request (Using CURL)

The following sample code is written in PHP and makes use of PHP’s CURL functionality.

$data = '<request>
	<install>
		<licenseKey>[LICENSE KEY] </licenseKey>
		<shopPath>http://www.example.com/store</shopPath>
		<sampleData>true</sampleData>
		<user>
			<email>administrator@example.com</email>
			<password>password</password>
		</user>
		<database>
			<dbUser>root</dbUser>
			<dbPass></dbPass>
			<dbDatabase>example_store</dbDatabase>
			<dbServer>localhost</dbServer>
			<tablePrefix>true</tablePrefix>
		</database>
		<sendStats>true</sendStats>
	</install>
</request>';
$ch = curl_init("http://www.example.com/store/admin/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	"Accept: application/xml",
	"Content-Type: application/xml"
));
echo "<pre>";
echo htmlspecialchars(curl_exec($ch));
echo "</pre>";

A Successful Installation Response

A successful installation will return an OK status as well as information about the newly installed store. The response will be formatted as XML.

XML Reference

  • response – The root node of the XML document. Outlining that this is a response to a previous XML request.
    • status – Will contain a value of OK for a successful installation.
    • shop
      • shopPath – The URL to the front end of the installed copy of Interspire Shopping Cart
      • controlPanel – The URL to the control panel of the installed copy of Interspire Shopping Cart
    • user
      • username – The username of the default store administrator
      • password – The previously assigned password (from the installation request) for this user

Sample Response

<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<status>OK</status>
	<shop>
		<shopPath>http://www.example.com/store/</shopPath>
		<controlPanel>http://www.example.com/store/admin/index.php</controlPanel>
	</shop>
	<user>
		<username>admin</username>
		<password>password</password>
	</user>
</response>

An Erroneous Installation Response

In the event that there is a problem during the installation, or the server does not meet the requirements for Interspire Shopping Cart, an XML response will be returned containing information about why the installation cannot proceed.

XML Reference

  • response – The root node of the XML document. Outlining that this is a response to a previous XML request.
    • status – Will contain a value of ERROR for an unsuccessful installation.
    • message – An overall message stating why the message cannot proceed.
    • errors
      • error – This node will be repeated for each error and can contain the following:
        • (Attribute) code An error code associated with this error. See Appendix 1: Error Codes for a full list of error codes
        • (Attribute / Optional) extra – Any additional information that may be useful to help debug this error.
        • Value – The value of the error node contains a friendly error message that can be shown as to why this problem occurred.

Sample Response

The following sample outlines the response you will receive from passing an invalid license key:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<status>ERROR</status>
	<message>The license key that you entered is invalid. You can generate your license key from the Interspire client area or purchase one from Interspire.com.</message>
	<errors>
		<error code="badLicenseKey">The license key that you entered is invalid. You can generate your license key from the Interspire client area or purchase one from Interspire.com.</error>
	</errors>
</response>

In the sample below, a few of the required directories are missing:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<status>ERROR</status>
	<message>Before you can install Interspire Shopping Cart you need to set the appropriate permissions on the files/folders listed below:</message>
	<errors>
		<error code="doesntExist" extra="product_downloads/a">The file/folder product_downloads/a doesn't exist. Please create it.</error>
		<error code="doesntExist" extra="product_downloads/b">The file/folder product_downloads/b doesn't exist. Please create it.</error>
	</errors>
</response>

Appendix 1: Error Codes

The table below outlines all of the possible return values for the error code attribute.

Code Extra Data Reason
badLicenseKey N/A The supplied license key was invalid.
missingShopPath N/A A shopPath value was not supplied containing the URL to the store.
missingUserEmail N/A A valid email address for the store administrator was not supplied.
missingUserPass N/A A valid password for the store administrator was not supplied.
missingDbServer N/A A database server hostname was not supplied.
missingDbDatabase N/A A database name was not supplied.
missingDbUser N/A A database username was not supplied.
mysqlVersion The version of MySQL currently running on the server. The version of MySQL running on the server does not meet the requirements for Interspire Shopping Cart.
unableSaveConfig N/A The configuration file was unable to be saved.
dbError The database message as returned from MySQL. There was an error message returned by the database server during the installation.
dbConnectError The database connection error message as returned from MySQL. There was an error connecting to the database server with the supplied details.
filePermissions The name of the file/folder that does not have the necessary permissions. The files listed do not have the necessary write permissions. They need to be chmod depending depending on returned message.
doesntExist The name of the file/folder that does not exist. The files listed do not exist. They need to be created before the installation can proceed.
phpVersion The version of PHP currently running on the server. The version of PHP running on the server does not meet the minimum requirements.
gdRequired N/A The PHP GD library is not installed on the server.