Introduction

SOAP is a XML-based protocol that allows applications to send messages in a standarized way over the Internet. The communication with SOAP boils down to a SOAP server and a SOAP client. Magento offers a SOAP server that allows you to communicate with Magento on a level that allows you to integrate Magento into your own application.

The benefit of using SOAP (or its rival XML-RPC) is that first of the communication is done through HTTP, so you don't need any extra holes in the firewall. Also there are numerous SOAP-clients and XML-RPC-clients out there, and with most of them you don't have to worry how the actual communication between your client and the Magento server is handled: The only thing you have to worry about is calling the right server-side API-method, which will return some kind of result, and knowing how to handle this result.

In this tutorial you will learn how to build a SOAP-client and use it to receive information from Magento.

Webserver requirements

For SOAP to work within the Magento application, the PHP SOAP extension ("soap.so") needs to be installed on the server. For RPM-based Linux distributions this is normally installed with the command "yum install php-soap". Note that the PHP SOAP extension is not the same thing as the PEAR SOAP extension.

You can check if your Magento application has full SOAP support by browsing to the page http://MAGENTO/api/?wsdl. It should give us a XML-document explaining more about the usage of SOAP. If you see the message "0 Unable to load Soap extension on the server", SOAP support is missing in the webserver.

Setting up a SOAP account

First of all you need a special proxy-user for SOAP. Within your application you will build a SOAP-client and this client will act a bit the same as a regular browser. It will request a certain "page" within the Magento application, but because this page is only accessible if you have the proper permissions, you need to create an user account.

Before we create the actual user we will need to create a role for this user first. Login on the Admin Panel as administrator and browse to System, then Webservices and then Roles. Create a new role and select the Resources this role gives access to.

In this example we will add a role "API Full Access" that has full access to all of the resources. In real life you should make a thorough study of which role with which permissions is sufficient for your goal. Adding an API user that can access and modify all resources opens up for a little of extra security risks.

After creating the role, we need to create an API user. Browse to System, then Webservices and then Roles. The new user needs of course an username and also an API key (which can seen as a password). Make note of this username and API key, because these are the details we need to configure in our SOAP client. We will assume the username "soaper" here. Before saving the new user, make sure the proper User Role is selected ("API Full Acccess").

Choosing a SOAP client

In this document we describe how to use a SOAP-client to connect to Magento. In fact the client is your entire custom application as it is talking to Magento through SOAP. But instead of building the SOAP-client completely from scratch we can choose to base our code upon some existing SOAP-library.

PHP 5 is shipped with a built-in class called SoapClient which allows you to build a SOAP-connection. The extension is only activated if PHP is configured and compiled with the --enable-soap option. In many PHP-setups this is not the case. Instead of recompiling PHP it is much easier in those scenarios to choose a different SOAP package. However, to use SOAP within Magento itself, this extension needs to be installed anyway. Using SoapClient on the same webserver where Magento is running should not pose a problem.

Within the PEAR archive for instance there is a package PEAR::SOAP available which includes a SOAP_Client class. With a UNIX-command like "pear install soap" this package can be installed. The Zend Framework also includes a Zend_Soap_Client class which is also available within the Magento application - handy when you want two Magento applications to communicate with eachother.

NuSoap used to be the de-facto standard for SOAP-clients under PHP4, but with PHP5 there are so many other cleaner alternatives that the use of NuSoap is not recommended. Even worse, if the PHP5 SOAP extension is activated it will create a conflict with NuSoap - even though there is a Google Code initiative to solve this problem, it is a hassle.

In this tutorial we will assume the usage of the PHP SoapClient.

Logging with the SOAP client

So let's create a simple PHP-script that allows us to login into Magento through SOAP. The logic is here that we first need to initialize a new SoapClient object with as argument the Magento SOAP URL.

// Magento login information 
$mage_url = 'http://MAGENTO/api/soap?wsdl'; 
$mage_user = 'soap_user'; 
$mage_api_key = '********'; 
// Initialize the SOAP client 
$soap = new SoapClient( $mage_url ); 
// Login to Magento 
$session_id = $soap->login( $mage_user, $mage_api_key );

After we have initialized the $soap-object we login with the API user-credentials created earlier. This will return a session-ID which we will need to reuse when calling other API-methods.

The login() method is actually not part of the SoapClient-class. The class transforms this method-call into another call to the magic method __soapCall() with the first argument set to "login" and as second argument an array of the arguments given to the original method "login()" (in this case the user credentials). This structure allows us to easily call any SOAP-method:

$response = $soap->getSomethingSpecific ( $arguments );

What's next?

So far we have seen just a bit of PHP-code. In the next tutorial in this series we will dive into the actual Magento API to retrieve data. Also we will see the more advanced options with the API.