Magento SOAP API In Depth Guide and Troubleshooting

In this blog post we will see in detail how magento implements soap api and how to troubleshoot it.

This blog is a continuation of the previous blog. Its important that you read the previous blog before this one.

Explaining The api.xml file

Lets look at each file of the api.xml which we created in detail and how its linked. Just to recap this our api.xml file

<?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>
                    <new translate="title" module="excellence_test">
                        <title>List of products2</title>
                        <method>items2</method>
                    </new>
                </methods>
            </xyz>
        </resources>
        <resources_alias>
            <test_product>xyz</test_product>
        </resources_alias>
        <v2>
            <resources_function_prefix>
                <xyz>excellenceTest</xyz>
            </resources_function_prefix>
        </v2>
        <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>

I have added an extra method “new” in api.xml in addition to previous api.xml

V1 SOAP
First lets look at how we did our SOAP call through php

$client = new SoapClient('http://127.0.0.1:81/magento/api/soap/?wsdl=1');
$session = $client->login('test_123', [email protected]');
$result = $client->call($session, 'test_product.list', array(array()));
$client->endSession($session);

So looking at above code, our method name was “test_product.list”
Lets see the process which magento employs to discover the actual model to call is as follow

1. Split the api call with “.”. So it “test_product” becomes the resourceName and “list” becomes the method.
2. Check the resource alias corresponding to resourceName. In our case “api->resources_alias->test_product” matches this. And the corresponding resource name we get is “xyz”.
3. Read all methods from “xyz” resource. “api->resources->xyz->methods->list” this matches our call exactly.
4. Now magento can read the “model” and “method” and call the function.

This is the broad nature of SOAP V1 call, and if understood properly can be very useful to debug V1 calls.

V2 SOAP
Next lets look at how we did our SOAP V2 call.

$client = new SoapClient('http://127.0.0.1:81/magento/api/v2_soap/?wsdl=1');
$session = $client->login('test_123', [email protected]');
$result = $client->excellenceTestList($session);

In this instead of the “call()” method, we used “excellenceTestList()” method.
Lets see how this matches our configuration files.

1. magento first matches the function name “excellenceTestList” to our wsdl.xml file. This should be defined in “portType->operation”
2. next magento reads all “api->v2->resources_function_prefix” and then does a substring on our function name.
so So “excellenceTest” matches our function “excellenceTestList”, so magento removes the first part and the method name is “List”. Also it takes the resourceName as “xyz”
3. At this point magento has formulated “xyz” as resource and “list” as method name, rest is same as the V1 call.

Sending Parameters in API

In the above examples we just saw how use SOAP api without any function parameters. Lets see how to pass parameters and what changes we need to make

V1 SOAP
For V1 we don’t need to make any changes in our configuration files.

$result = $client->call($session, 'test_product.new', array(10,12));
$client->endSession($session);
echo '<pre>';
print_r($result);

in our model file

public function items2($param,$param2) {
        return $param.$param;
    }

similarly we can pass any kind of parameters, it won’t matter.

V2 SOAP
It not so simple in V2 SOAP, since we need to make changes to our wsdl.xml file

In our wsdl file we have “input” tag defined which tells what the parameters will be

<operation name="excellenceTestList">
            <documentation>List of products</documentation>
            <input message="typens:excellenceTestListRequest" />
            <output message="typens:excellenceTestListResponse" />
        </operation>

If we open the “excellenceTestListRequest”

<message name="excellenceTestListRequest">
        <part name="sessionId" type="xsd:string" />
    </message>

We need to change this as per our request.

e.g

<message name="excellenceTestListRequest">
        <part name="sessionId" type="xsd:string" />
        <part name="param" type="xsd:string" />
    </message>

We added a new part param

$client = new SoapClient('http://127.0.0.1:81/magento/api/v2_soap/?wsdl=1');
$session = $client->login('test_123', [email protected]');
$result = $client->excellenceTestNew($session,'test');
$client->endSession($session);

Now we can send a string type parameter. So for SOAP V2, any changes in request/response we need to make changes to our wsdl.xml file

Troubleshooting

SOAP V1

Fatal error: Uncaught SoapFault exception: [3] Invalid api path
This error comes up when the string parameter in call() doesn’t match the xml file.
Both should match, before and after the dot. The string before dot should match “resources_alias” tag and after dot should match the corresponding methods.

SOAP V2
First make sure that V1 calls are working fine or not.
Fatal error: Uncaught SoapFault exception: [Client] Function (“excellenceTestNew1”) is not a valid method for this service
This kind of error message shows up if functional name doesn’t match function name defined in wsdl file.

Fatal error: Uncaught SoapFault exception: [3] Invalid api path.
This error shows up if the there is some problem in “resources_function_prefix” matching, as described above.