In this series, we're discussing custom APIs in Magento.
In the first part, we created a full-fledged custom module to implement the custom API, in which we created the required files to plug in the custom APIs provided by our module.
In this second and last part, we'll go through the back-end section to demonstrate how to consume the APIs.
Let's have a quick recap of the first part. Here's the list of files we've already created:
- app/etc/modules/Envato_All.xml: It's a file used to enable our custom module.
- app/code/local/Envato/Customapimodule/etc/config.xml: It's a module configuration file.
- app/code/local/Envato/Customapimodule/etc/api.xml: It's a file which declares the APIs provided by our module.
- app/code/local/Envato/Customapimodule/etc/wsdl.xml: In this file, we'll define the API methods as per the convention of WSDL.
- app/code/local/Envato/Customapimodule/Helper/Data.php: It's a file used by the Magento translation system.
- app/code/local/Envato/Customapimodule/Model/Product/Api.php: It's a model file which implements the logic for our API methods.
- app/code/local/Envato/Customapimodule/Model/Product/Api/V2.php: It's a file to support Magento's v2 API.
Also, if you've already enabled our custom module, you should see that our API method "customapimoduleProductList" is listed along with the other APIs when you visit the http://yourmagentostore/api/v2_soap?wsdl=1 page which lists all available APIs in Magento.
Magento supports "API Roles" and "API Users". We need "API Roles" since you don't want to allow the user access to each and every API of Magento. The "API Roles" are used to create roles with limited access permissions to the API resources.
For example, you could create a role which only allows read-only access to the "Product Listing" APIs. On the other hand, you could create a role which allows catalog modification, and it'll be only assigned to the "authorized" users only!
Set Up "API User" and "API Role" From the Back-End
In this section, we'll create a demo "API Role" and "API User". Later on, we'll use these to consume the custom APIs provided by our module. Head over to the Magento back-end!
Set Up an API Role
Go to System > Web Services > (SOAP/XMLRPC) Roles. Click on Add New Role to create a new role. Under the Role Info tab, I've entered "Demo SOAP Role" in the Role Name field.
Next, under the Role Resources tab, you'll see the different resources with check boxes. Click on the Products > Product data check-box. It means that "Demo SOAP Role" can only access the "Product data" resource APIs. Click on the Save Role button to save the role information.
Set Up an API User
Now, let's create the API user and assign the "Demo SOAP Role" to that user. Go to System > Web Services > (SOAP/XMLRPC) Users. Click on Add New User to create a new user. Under the User Info tab, please fill in the required information.
Further, under the User Role tab select the Demo SOAP Role radio button. Click on the Save User button to save the user information.
So that's it—we've set up the required role and user to access the Magento APIs!
How to Consume the Magento API
In this section, we'll see how to call the Magento APIs. Under your document root, create an example PHP file and fill it with the following contents.
<?php // v2 call $client = new SoapClient('http://www.yourmagentostore.com/api/v2_soap/?wsdl=1'); $session = $client->login('soapuser', 'soapuser'); $result = $client->customapimoduleProductList($session); $client->endSession($session); echo '<pre>'; print_r($result); // v1 call $client = new SoapClient('http://www.yourmagentostore.com/api/soap/?wsdl=1'); $session = $client->login('soapuser', 'soapuser'); $result = $client->call($session, 'product.list', array(array())); $client->endSession($session); echo '<pre>'; print_r($result);
Change "http://www.yourmagentostore.com" to your Magento store URL. As I mentioned earlier, Magento supports two versions of the APIs, v1 and v2. In this example, I've demonstrated both the ways.
In v2 API mode, first we create a new instance of the "SoapClient" class. Next, we call the "login" method to log in to the Magento store—of course we'll need to provide the username and password of the "API User" created in the earlier section. Finally, we call the "customapimoduleProductList" method to retrieve the list of products! The
$session variable is passed as an input parameter to the method to claim the authenticity of the method. An important thing to note here is that "customapimoduleProduct" is the resource prefix and "list" is the method name.
In v1 API mode, the only different part is the calling of the API method. We are using a generic "call" method, in which a "method name" and other parameters are passed as arguments. As you can see, the "product" is used as a resource prefix and "list" is the method name!
So that sums up the series! Now you should feel comfortable with the Magento APIs, and you can create custom APIs as per your requirements! Feel free to shoot your suggestions and feedback!