Page tree
Skip to end of metadata
Go to start of metadata

There are a few posts/articles outlining how to create your own api or extending an existing Mage api class but none of them to my knowledge show you how to add extra functionality to a base api class.

If the function already exists then sure you can override it, but what happens when you want to add a new function? Well you get a soap exception informing you that the member function doesn’t exist.

This article will address some of the issues I encountered and show you how to extend the magento catalog api to add an additional function to return products assigned to a category in more detail.

Skill level: Beginning to Advanced developer.

Target Audience: Developers who need to customize PHP Code.

Tested with Magento versions:

Should be applicable for all Magento versions (1.1.x and older).

Create Module Structure

You will want to make a module that represents your company to hold all your specific changes, I’ve called mineMyCompany you can obviously call it what you like.

Start off by making a new directory structure like so

app /
    code /
        local /
            MyCompany /
                Catalog /
                    etc /
                    Model /
                        Category /
                            Api /
app /
    etc /
        modules /


Activate your new module

Now, you must activate your module so Magento understands that there is new code in the local directory.

 Expand source

It is crucial that the same prefix MyCompany is used throughout the files, class names, directories, and XML tag names.

Define module's configuration

 Expand source

Here we are going to configure our module letting magento know which model classes to use and any class dependencies.

We make use of the <depends> tag to tell magento that this class depends on the Mage_Catalog class.

And we make use of the <rewrite> tag to tell magento to use this class in place of the core classMage_Catalog_Category_Model_Api which is the class we are extending. We are extending both the SOAP v1 and SOAPv2 api which is why we have two tags under the rewrite tag.

Note: If you have any classes in a folder below your module then you can address it by seperating it with an underscore. i.e. module_api_v2

The data inside the tag under the <rewrite> tag is the name of your class file, and Magento knows how to find it because the class name is the same as it’s directory path and filename. Remember that the underscore means another folder level on the file structure, and Magento won’t find your class if the folder structure doesn’t reflect the class name properly.

For instance:

MyCompany_Catalog_Model_Category_Api = /app/code/local/MyCompany/Catalog/Model/Category/Api.phpMyCompany_Catalog_Model_Category_Api_v2 = /app/code/local/MyCompany/Catalog/Model/Category/Api/v2.php

Define your module's api and methods

Here we are going to tell magento about our module’s api and which methods are available and any aliases pointing to this api.

 Expand source

Resource Name, Aliases and Prefixes

The resource name is the name of the tag below <resources> and I believe you can call it what you like as long as you add the necessary xml to the wsdl.xml file.

I have used the same <resources_alias> as the Mage_Catalog api, which the way I understand it should work, although I may be wrong.

The <v2> and <resources_function_prefix> tags define what the SOAP v2 method will be called, which by magento standards is the resource name in camel case without underscores. i.e. resourceName

For SOAP v2 calls you use the following syntax

$client->ResourceNameMethodName($session, $args)

which magento generates for you based on the defined resources xml in your api.xml (its actually an alias to ResourceName.MethodName) - more on SOAP v2 calls later...

If you wanted you could create your own aliases and resource names to distinguish between the Magento ones, but as we are adding this method to the overall wsdl (Web Services Description Language) I figure we might as well provide access via the standard api alias catalog_category.


Here in the <model> tag we specify which model class the api will use, which is a reference to the structure below our Model directory. Category/Api

From what I can tell we don’t need to reference the Category/Api/v2.php as it seems to work without. Hopefully one of the magento team will provide a bit more insight to the available xml tags and what is required for soap_v2.

Method Name

The tag <assignedProductsDetail> is the name of our new function/method we are going to make available to the api.

Access Control lists (ACL)

The <acl> tag defines an access control list restricting access to this method to users who have this role resource set. see Admin > System > Web Services > Roles.

You can create custom <acl> entries in your api.xml files if you wish, I have made use of the<acl>catalog/category/product</acl> for managing access to categories > product(s).

The acl can be defined in the api.xml file and I suggest you take a look at


for further information.


You can also define <faults> which are the messages sent in response to missing/invalid arguments etc.


The wdsl.xml file is where you define your methods in more detail describing your inputs and outputs - the type of data accepted/returned.



 Expand source


Here I have defined the catalogAssignedProductDetail and catalogAssignedProductDetailArray complex types which is basically telling the soap protocol more about the returned data/message. You could point thecatalogAssignedProductDetail to use the already defined catalogProductReturnEntity which I am yet to test, this would allow for future changes.

I have also added <parts> to the <message name=”catalogCategoryAssignedProductsDetailRequest”> tag which lists what arguments I’m expecting and their type-safe types. One of the key <parts> here is the <filters> which allows me to pass additional product filters to my function as an array.

This wsdl.xml is merged along with other mage wsdl files like




so when you access the SOAP v2 url http://localhost/magento/index.php/api/v2_soap?wsdl you should see your additional declarations.

Note: If you do not see your additional declarations then it is possible that you are viewing a cached version of the wsdl. To refresh, remove any magento wsdl files stored in the /tmp folder (usually /tmp or C:/tmp).

You can also auto-generate your wsdl.xml based on your php-doc comments, haven’t tried it myself yet.

API Classes

Here we are extending the Mage_Catalog_Model_Category_Api base class, if we were writing our own class from scratch based on the Catalog/Model then we would extend Mage_Catalog_Model_Api_Resource instead.

We are creating two classes one for SOAP v1 calls and another for SOAP v2 calls the main difference between the two is the way you treat arrays as per the SOAP v2 protocol.

SOAP v1 Class

 Expand source

SOAP v2 Class

 Expand source

Making SOAP calls to your new method

Create Web Service Role

In your magento admin control panel goto System > Web Services > Roles and click on Add Role

  • Enter a Role Name - MyCompany for example
  • Select Resources tab and select which resources you want this api user to have access to
  • Click Save

Note: If you plan to develop a module that only extends the Catalog class then it’s best to limit what resources the api user has access to. You should consider that this will open up your magento store for access over http/https from an external source. Use the drop-down to select All if you want to grant full access.

The <acl> declarations we set earlier lookup access permissions based on these roles.

Create Web Service User

In your magento admin control panel goto System > Web Services > Users and click on Add User

  • Enter a User Name - MyCompany for example (this is what we will use in the SOAP_USER define later).
  • Enter a First Name and Last Name - e.g. My Company | API User
  • Enter an email address - e.g.
  • Enter an API key - this can be anything you want and I just use 123456 for development purposes.
  • Select User Role tab and select the role you want this api user to be a member of.
  • Click Save

Note: I know its pretty obvious, but for the beginners out there, for production use I would strongly suggest you make up a passphrase and hash it using md5 or similar, its near impossible to decrypt md5 and you don’t want anyone guessing your api key. I would also keep a regular eye on your apache log files to ensure no unauthorised access has occurred using this api user. The API key can always be changed if necessary.

php echo md5('passphrase')

Test Script

I have created a basic script to illustrate how to call your new soap method using both versions, just copy this into a blank file and name it test.php.

 Expand source


To test using SOAP v1 use: http://localhost/magento/test.php?ver=1 To test using SOAP v2 use:http://localhost/magento/test.php?ver=2



  • No labels