Introduction

For any successful platform, it's vital to keep up with the cutting edge features and provide them to compete in the market. Exposing APIs for your platform is one of the important features which allows integration with third-party systems, thus opening the doors to reach the larger community. Magento, being one of the most successful e­Commerce platforms, provides a plethora of useful features and utilities which proves it a truly enterprise level framework.

Exposing APIs for your resources is beneficial in many ways. One of the most apparent is that it makes your resources available on different platforms, thus making them platform independent, thanks to protocols like XML­-RPC/SOAP, which allows you to expose your resources in a streamlined manner. We'll use SOAP for our custom module.

In this tutorial, we'll create a custom module "Customapimodule". I assume that you're familiar with the basic module creation process in Magento. Here's a nice article explaining the basics of custom module creation.

A Glance at the File Setup

Here's the list of files required for the desired setup:

• 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 conventions 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 of our API methods.
• app/code/local/Envato/Customapimodule/Model/Product/Api/V2.php: It's a file to support Magento's v2 API.

Custom Module Creation: Setting Up the Files

To start with, we'll create a module enabler file. Create a file "app/etc/modules/Envato_All.xml" and paste the following contents in that file. We've used "Envato" as our module namespace and "Customapimodule" as our module name. It'll enable our "Customapimodule" module by default.

<?xml version="1.0"?>
<config>
  <modules>
    <Envato_Customapimodule>
      <active>true</active>
      <codePool>local</codePool>
    </Envato_Customapimodule>
  </modules>
</config>

Next, we need to create a module configuration file. Create "app/code/local/Envato/Customapimodule/etc/config.xml" and paste the following contents in that file.

<?xml version="1.0"?>
<config>
  <modules>
    <Envato_Customapimodule>
      <version>1.0</version>
    </Envato_Customapimodule>
  </modules>
  <global>
    <models>
      <customapimodule>
        <class>Envato_Customapimodule_Model</class>
      </customapimodule>
    </models>
    <helpers>
      <customapimodule>
        <class>Envato_Customapimodule_Helper</class>
      </customapimodule>
    </helpers>
  </global>
</config>

Nothing fancy here—we've just declared the "Model" and "Helper" classes as per the Magento conventions.

Moving ahead, create "app/code/local/Envato/Customapimodule/etc/api.xml" and paste the following contents in that file. The "api.xml" file is used to declare the API methods exposed by your module.

<?xml version="1.0"?>
<config>
  <api>
    <resources>
      <customapimodule_product translate="title" module="customapimodule">
        <model>customapimodule/product_api</model>
        <title>Demo Custommoduleapi API</title>
        <acl>customapimodule/product</acl>
        <methods>
          <list translate="title" module="customapimodule">
            <title>List of products</title>
            <method>items</method>
          </list>
        </methods>
      </customapimodule_product>
    </resources>
    <resources_alias>
      <product>customapimodule_product</product>
    </resources_alias>
    <v2>
      <resources_function_prefix>
         <product>customapimoduleProduct</product>
      </resources_function_prefix>
    </v2>
    <acl>
      <resources>
        <customapimodule translate="title" module="customapimodule">
          <title>Products</title>
          <sort_order>5</sort_order>
          <product translate="title" module="customapimodule">
            <title>Product data</title>
          </product>
        </customapimodule>
      </resources>
    </acl>
  </api>
</config>

We'll start with the <resources> tag, which wraps all the resources declared by your module. You could think of "resource" as an entity, using which you would like to categorize your API methods. 

In our example, we've just declared a single resource named <customapimodule_product>. You can name it whatever you like, as long as it's a unique identifier. Under the <customapimodule_product> resource tag, we've declared the <model> tag to link the Magento "Model" file, where we'll define the API method definitions. The methods for our resources are wrapped by the <methods> tag. In our case, we've only defined a single method, "items", under the <list> tag, which will provide a list of products.

Further, the <acl> tag under <customapimodule_product> is used to provide access control for our resources. The value defined in the <acl> tag "customapimodule/product" references the definition at the bottom of the file. 

At the bottom of the file, you can see that we've declared a separate <acl> tag which defines the "customapimodule/product". In short, it's used to put our resources under access control, so that they can be accessed by certain "API Roles" if they're defined in that way in the Magento back­-end. We'll discuss this more in detail in the next part of this tutorial.

At the moment, two versions of the Magento API are supported, v1 and v2, using which you can create and expose APIs. In our example, we'll see both the methods. The <resources_alias> tag is used to define a resource alias name by which our method will be called. We've defined it as <product>, so whenever you want to call an API method using Magento v1 API, you will use "product" as a resource prefix. In the same way <v2> defines a resource alias for the Magento v2 API, so the resource prefix will be "customapimoduleProduct". These things will be clearer when we see how to call our APIs in the next tutorial.

Next, let's create the "app/code/local/Envato/Customapimodule/etc/wsdl.xml" file and paste the following contents.

<?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>
    </schema>
  </types>
  <message name="customapimoduleProductListRequest">
    <part name="sessionId" type="xsd:string" />
  </message>
  <message name="customapimoduleProductListResponse">
    <part name="products" type="typens:fieldInfoArray" />
  </message>
  <portType name="{{var wsdl.handler}}PortType">
    <operation name="customapimoduleProductList">
      <documentation>List of products</documentation>
      <input message="typens:customapimoduleProductListRequest" />
      <output message="typens:customapimoduleProductListResponse" />
    </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="customapimoduleProductList">
      <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>

The "wsdl.xml" file is used to define the API method definitions as per the SOAP syntax. We'll see some of the important tags in this file in the context of this tutorial. 

First, we've defined the "fieldInfo" complex type, which contains two elements: "entity_id" and "name". Further, we've defined the "fieldInfoArray" complex type, which is derived from the "fieldInfo" complex type. It's an array of the "fieldInfo" complex type. 

In simple terms, we've defined the object properties which will be returned in the response of the API method call. In our case, we'll return an array of products. Each item of an array will have two properties: "entity_id" and "name" of the product. You can define more properties as per your requirements.

Next, under the <message> tag "customapimoduleProductListRequest", we've defined the input parameters required using the <part> tag. In the same way, under the <message> tag "customapimoduleProductListResponse", we've defined the type of the output objects. When we call an API method, we need to pass "sessionId", and the response of the API method will contain the array of products. The rest of the tags will make our method appear when you call http://yourmagentostore/api/v2_soap?wsdl=1.

Next, we'll need to create the "app/code/local/Envato/Customapimodule/Helper/Data.php" file just to make sure the translation system of Magento works properly. It's almost an empty file, but should be there as per the conventions!

<?php
class Envato_Customapimodule_Helper_Data extends Mage_Core_Helper_Abstract
{
}

Next, let's create a model file "app/code/local/Envato/Customapimodule/Model/Product/Api.php".

<?php
// app/code/local/Envato/Customapimodule/Model/Product/Api.php
class Envato_Customapimodule_Model_Product_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;
  }
}

Recall that earlier in the "api.xml" we defined an "items" method wrapped by a <list> tag. So in the above model class, we've just implemented this. 

In this method, we simply fetch five recent products, and iterate through each of the items to prepare an array of products with the properties "entity_id" and "name". So now you should probably understand the reason for the "Complex Type" created in "wsdl.xml"!

Further, we also need to create a model file to support the Magento v2 API. Let's create a model file "app/code/local/Envato/Customapimodule/Model/Product/Api/v2.php" with the following contents.

<?php
//app/code/local/Envato/Customapimodule/Model/Product/Api/V2.php
class Envato_Customapimodule_Model_Product_Api_V2 extends Envato_Customapimodule_Model_Product_Api
{
}

As you can see, it's just extending a model class defined earlier in the "app/code/local/Envato/Customapimodule/Model/Product/Api.php" file.

So that's it as far as the file setup is concerned for the custom API implementation. If you're curious, enable the module from the back­-end and clear the cache. Now, when you visit the http://yourmagentostore/api/v2_soap?wsdl=1 page, you should see our method "customapimoduleProductList" is listed along with the other APIs!

In the next part, we'll go ahead and see how to create API user and API role, and of course, how to use our custom API method defined in this tutorial!