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: 220.127.116.11
Should be applicable for all Magento versions (1.1.x and older).
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.
app / code / local / MyCompany / Catalog / etc / api.xml config.xml wsdl.xml Model / Category / Api / v2.php Api.php app / etc / modules / MyCompany_Catalog.xml
Now, you must activate your module so Magento understands that there is new code in the local directory.
It is crucial that the same prefix MyCompany is used throughout the files, class names, directories, and XML tag names.
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.
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
Here we are going to tell magento about our module’s api and which methods are available and any aliases pointing to this api.
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
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.
The tag <assignedProductsDetail> is the name of our new function/method we are going to make available to the api.
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.
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.
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.
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.
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. firstname.lastname@example.org
- 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')
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.