Magento SOAP API V1 and V2

In this blog post we look into an overview of how to create soap api in magento.

I hope you are familiar with basic concepts creating magento module, what is SOAP and how to create a SOAP User, Role from magento. There are many tutorials available online for these hence won’t be covering these again.

First create a simple magento module with a config.xml file, a helper, block folder and model folder.
Lets assume the name of module to be Excellence_Test

Step1

We need to create a api.xml file in etc/ folder of the module. api.xml is the main configuration file for your SOAP Api.

Write the following code in it

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <api>
        <resources>
            <xyz translate="title" module="excellence_test">
                <model>excellence_test/api</model>
                <title>Demo API</title>
                <acl>test/api</acl>
                <methods>
                    <list translate="title" module="excellence_test">
                        <title>List of products</title>
                        <method>items</method>
                    </list>
                </methods>
            </xyz>
        </resources>
        <resources_alias>
            <test_product>xyz</test_product>
        </resources_alias>
        <acl>
            <resources>
                <test translate="title" module="excellence_test">
                    <title>Test ACL Title</title>
                    <sort_order>5</sort_order>
                    <api translate="title" module="excellence_test">
                        <title>Test SOAP API ACL</title>
                    </api>
                </test>
            </resources>
        </acl>
    </api>
</config>

Above is the most basic api.xml configuration for only SOAP V1 api. We will look into the xml configuration in detail later.

Step2

Create the api model file. In the api.xml file we have mentioned the model to be “excellence_test/api” so we need to create the file

<?php
class Excellence_Test_Model_Api extends Mage_Api_Model_Resource_Abstract {

    public function items() {
        $arr_products = array();
        $products = Mage::getModel("catalog/product")
                ->getCollection()
                ->addAttributeToSelect('*')
                ->setOrder('entity_id', 'DESC')
                ->setPageSize(5);

        foreach ($products as $product) {
            $arr_products[] = $product->toArray(array('entity_id', 'name'));
        }
        return $arr_products;
    }

}

The model needs to extend Mage_Api_Model_Resource_Abstract and it needs to define the function written in method tag in our api.xml file

Step3

Next we need to create api user and role. This can be created from Admin -> System Configuration -> Web Services -> SOAP-XML/RPC User/Role. This section is self explanatory and there are many tutorials online for this.
After doing this you should have “username” and “api_key” with you.

At this point we have a running V1 SOAP API. To test if the api is working, we need to write a simple php code.

Create a test.php file, in the magento root folder.
Write this code

$client = new SoapClient('http://127.0.0.1:81/magento/api/soap/?wsdl=1');
$session = $client->login('api_username', 'api_password');
$result = $client->call($session, 'test_product.list', array(array()));
$client->endSession($session);
echo '<pre>';
print_r($result);

If you run this file, it should return output.

Step4

Add the below xml configuration next to the resource_alias tag.

        <v2>
            <resources_function_prefix>
                <xyz>customapimoduleProduct</xyz>
            </resources_function_prefix>
        </v2>

Step5

Create wsdl.xml file in etc/ folder of your module.
Paste this code in your xml file

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:typens="urn:{{var wsdl.name}}" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"
             name="{{var wsdl.name}}" targetNamespace="urn:{{var wsdl.name}}">
    <types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:Magento">
            <import namespace="http://schemas.xmlsoap.org/soap/encoding/" schemaLocation="http://schemas.xmlsoap.org/soap/encoding/" />
            <complexType name="fieldInfo">
                <sequence>
                    <element name="entity_id" type="xsd:string"/>
                    <element name="name" type="xsd:string"/>
                </sequence>
            </complexType>
            <complexType name="fieldInfoArray">
                <complexContent>
                    <restriction base="soapenc:Array">
                        <attribute ref="soapenc:arrayType" wsdl:arrayType="typens:fieldInfo[]" />
                    </restriction>
                </complexContent>
            </complexType>
            <complexType name="newFieldInfo">
                <all>
                    <element name='test' type="xsd:int"></element>
                </all>
            </complexType>
        </schema>
    </types>
    <message name="excellenceTestListRequest">
        <part name="sessionId" type="xsd:string" />
    </message>
    <message name="excellenceTestListResponse">
        <part name="products" type="typens:fieldInfoArray" />
    </message>
    <portType name="{{var wsdl.handler}}PortType">
        <operation name="excellenceTestList">
            <documentation>List of products</documentation>
            <input message="typens:excellenceTestListRequest" />
            <output message="typens:excellenceTestListResponse" />
        </operation>
    </portType>
    <binding name="{{var wsdl.handler}}Binding" type="typens:{{var wsdl.handler}}PortType">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
        <operation name="excellenceTestList">
            <soap:operation soapAction="urn:{{var wsdl.handler}}Action" />
            <input>
                <soap:body namespace="urn:{{var wsdl.name}}" use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
            </input>
            <output>
                <soap:body namespace="urn:{{var wsdl.name}}" use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
            </output>
        </operation>
    </binding>
    <service name="{{var wsdl.name}}Service">
        <port name="{{var wsdl.handler}}Port" binding="typens:{{var wsdl.handler}}Binding">
            <soap:address location="{{var wsdl.url}}" />
        </port>
    </service>
</definitions>

Step6

We need to creat a model file as well. For V2 calls, magento automatically adds suffix V2 to existing model defined.
In our case the model we defined was “excellence_test/api”, magento will automatically add “excellence_test/api_v2”

So we need to create a V2 file

<?php
class Excellence_Test_Model_Api_V2 extends Excellence_Test_Model_Api {

}

This model simply extends the V1 api, so this file will be empty only.

At this point even your SOAP V2 api should be ready.
To test add this code to your previous test.php file

$client = new SoapClient('http://127.0.0.1:81/magento/api/v2_soap/?wsdl=1');
$session = $client->login('api_username', 'api_key');
$result = $client->excellenceTestList($session);
$client->endSession($session);
echo '<pre>';
print_r($result);