It is not in-depth tutorial but description on how I tackled creation of custom API for magento. There are still vast fields of unknown but at least this will let you start building your own API and let you learn, like me, on how to do it. If I will find out anything new about it or I will gain some theoretical knowledge then I will update this post with those revelations.
\n
\nEven the simplest example involves fairly few files and folders to be created, in this example we will create method which will return the version of the installed magento and list of best selling products, this is the structure of it:<\/p>\n
\r\nmagento\/app\/\r\n |- code\/community\/\r\n\t| |- GrelaDesign\/\r\n\t|\t |- Tutorial\/\r\n\t| |- etc\/\r\n\t| |- api.xml\r\n\t| |- config.xml\r\n | |- Helper\/\r\n | |- Data.php\r\n\t| |- Model\/\r\n\t| |- Core\/\r\n\t| |- Api.php\r\n\t| |- DashBoard\/\r\n\t| |- Api.php\r\n |- etc\/modules\/\r\n\t |- GrelaDesign_Tutorial.xml\r\n<\/pre>\ngeneral structure would look like:<\/p>\n
\r\nmagento\/app\/code\/\r\n |- community\/ or local\/ or core\/\r\n | |- COMPANYNAME\/\r\n | |- MODULENAME\/\r\n | |- etc\/\r\n | |- api.xml\r\n | |- config.xml\r\n | |- Helper\/\r\n | |- Data.php\r\n | |- Model\/\r\n | |- OBJECT1\/\r\n | |- Api.php\r\n | |- Object2\/\r\n | |- Api.php\r\n |- etc\/modules\/\r\n |- COMPANYNAME_MODULE.xml\r\n\r\n<\/pre>\nOnce you have created tutorial structure let’s start to fill it with content:<\/p>\n
This file instructs magento where to find our API<\/p>\n
\r\n<!-- GrelaDesign_Tutorial.xml -->\r\n<config>\r\n\t<modules>\r\n\t\t<GrelaDesign_Tutorial>\r\n\t\t\t<active>true<\/active>\r\n\t\t\t<codePool>community<\/codePool><!-- this could be also 'local' -->\r\n\t\t\t<depends>\r\n\t\t\t\t<Mage_Api \/>\r\n\t\t\t<\/depends>\r\n\t\t<\/GrelaDesign_Tutorial>\r\n\t<\/modules>\r\n<\/config>\r\n<\/pre>\nconfig file, point to the model and helper, also to the translation files but I haven’t got this to work so far:), also in this revised version I have added a helper node as it seems to be quite important for Magento, without it I had an error thrown when I tried to access system->web services->roles and add\/edit role.<\/p>\n
\r\n<!-- config.xml -->\r\n<config>\r\n\t<modules>\r\n\t\t<GrelaDesign_Tutorial><!-- COMPANYNAME_MODULE -->\r\n\t\t\t<version>0.0.0.1<\/version>\r\n\t\t<\/GrelaDesign_Tutorial>\r\n\t<\/modules>\r\n\t<global>\r\n\t\t<models>\r\n\t\t\t<tutorial><!-- MODULE, just first letter is lowercased, i.e. module CustomAPI would be placed here as customAPI -->\r\n\t\t\t\t<class>GrelaDesign_Tutorial_Model<\/class>\r\n\t\t\t<\/tutorial>\r\n\t\t<\/models>\r\n\t\t<helpers>\r\n\t\t\t<tutorial>\r\n\t\t\t\t<class>GrelaDesign_Tutorial_Helper<\/class>\r\n\t\t\t<\/tutorial>\r\n\t\t<\/helpers>\r\n\t<\/global>\r\n<\/config>\r\n<\/pre>\nIn this tutorial we will create
two<\/del> three methods for our API, I have deliberately placed them in different classes to show how it affects look of api.xml file. First will be getVersion in Core object, second will be getBestsellers in DashBoard object and third getTotals also in DashBoard object.<\/p>\nThe api.xml defines the resource name, by which programmer will call our exposed methods and will define Access Control Lists (ACL). The ACL is a way of grouping our methods into logical sets from which we will select (mix’n’match) when creating rules and webservices users. In our example we will have 2 sets of access groups: “allaccess” and “owneracess”. First will mark those methods that has no restrictions, and second marks the methods that only the “owner” user can access.<\/p>\n
“allaccess”
\n\t– getVersion
\n\t– getBestsellers
\n“owneraccess”
\n\t– getTotals<\/p>\n\r\n<!-- api.xml -->\r\n<config>\r\n\t<api>\r\n\t\t<resources>\r\n\t\t\t<tutorial_core translate="title" module="tutorial">\r\n\t\t\t\t<title>GrelaDesign tutorial Core API calls<\/title>\r\n\t\t\t\t<model>tutorial\/core_api<\/model>\r\n\t\t\t\t<acl>greladesign\/tutorial<\/acl>\r\n\t\t\t\t<methods>\r\n\t\t\t\t\t<getVersion translate="title" module="tutorial">\r\n\t\t\t\t\t\t<title>Returns version of this API<\/title>\r\n\t\t\t\t\t\t<acl>greladesign\/tutorial\/allaccess<\/acl>\r\n\t\t\t\t\t<\/getVersion>\r\n\t\t\t\t<\/methods>\r\n\t\t\t<\/tutorial_core>\r\n\t\t\t<tutorial_dashboard translate="title" module="tutorial">\r\n\t\t\t\t<title>GrelaDesign tutorial DashBoard app API calls<\/title>\r\n\t\t\t\t<model>tutorial\/dashBoard_api<\/model>\r\n\t\t\t\t<acl>greladesign\/tutorial<\/acl>\r\n\t\t\t\t<methods>\r\n\t\t\t\t\t<getSalesTotals translate="title" module="tutorial">\r\n\t\t\t\t\t\t<title>Get sales totals<\/title>\r\n\t\t\t\t\t\t<method>getTotals<\/method><!-- here we specify the method name if we have a conflict with built in method or we want to change the name i.e. because it is lengthy -->\r\n\t\t\t\t\t\t<acl>greladesign\/tutorial\/owneraccess<\/acl>\r\n\t\t\t\t\t<\/getSalesTotals>\r\n\t\t\t\t\t<getBestsellers translate="title" module="tutorial">\r\n\t\t\t\t\t\t<title>Get best selling product list<\/title>\r\n\t\t\t\t\t\t<acl>greladesign\/tutorial\/allaccess<\/acl>\r\n\t\t\t\t\t<\/getBestsellers>\r\n\t\t\t\t<\/methods>\r\n\t\t\t<\/tutorial_dashboard>\r\n\t\t<\/resources>\r\n\t\t<resources_alias><!-- here we can put aliases, shortened calls for our api resource, I haven't checked how alias behaves when it collides with different resource... -->\r\n\t\t\t<dashboard>tutorial_dashboard<\/dashboard>\r\n\t\t\t<core>tutorial_core<\/core>\r\n\t\t<\/resources_alias>\r\n\t\t<acl><!-- Access Control List to our resources, this tree structure is displayed in "Resource Roles" panel when you open role to edit -->\r\n\t\t\t<resources>\r\n\t\t\t\t<greladesign translate="title" module="tutorial">\r\n\t\t\t\t\t<title>GrelaDesign<\/title>\r\n\t\t\t\t\t<sort_order>100<\/sort_order>\r\n\t\t\t\t\t<tutorial translate="title" module="tutorial">\r\n\t\t\t\t\t\t<title>Tutorial<\/title>\r\n\t\t\t\t\t\t<sort_order>100<\/sort_order>\r\n\t\t\t\t\t\t<allaccess translate="title" module="tutorial">\r\n\t\t\t\t\t\t\t<title>Core functionality required by all users.<\/title>\r\n\t\t\t\t\t\t\t<sort_order>10<\/sort_order>\r\n\t\t\t\t\t\t<\/allaccess>\r\n\t\t\t\t\t\t<owneraccess translate="title" module="tutorial">\r\n\t\t\t\t\t\t\t<title>Functions accessible only for owner.<\/title>\r\n\t\t\t\t\t\t\t<sort_order>50<\/sort_order>\r\n\t\t\t\t\t\t<\/owneraccess>\r\n\t\t\t\t\t<\/tutorial>\r\n\t\t\t\t<\/greladesign>\r\n\t\t\t<\/resources>\r\n\t\t<\/acl>\r\n\t<\/api>\r\n<\/config>\r\n<\/pre>\nRe-assuming: config->api->resources lists api resources with the exposed methods, config->api->acl->resources defines access groups for our resources<\/p>\n
All we need to do now is just the API methods, lets start from the easiest:<\/p>\n
\r\n<!-- magento\/app\/code\/community\/GrelaDesign\/Tutorial\/Model\/Core\/Api.php -->\r\n<?php\r\nclass GrelaDesign_Tutorial_Model_Core_Api\r\n{\r\n\t\/**\r\n\t * Returns version of the installed magento\r\n\t * @return String\r\n\t *\/\r\n\tpublic function getVersion()\r\n\t{\r\n\t\treturn Mage::getVersion();\r\n\t}\r\n}\r\n?>\r\n<\/pre>\nSimple isn’t it? Next will be more complex, but thanks to the snippi.net I was able to create it with no time, almost:)<\/p>\n
\r\n<!-- magento\/app\/code\/community\/GrelaDesign\/Tutorial\/Model\/DashBoard\/Api.php -->\r\n<?php\r\nclass GrelaDesign_Tutorial_Model_DashBoard_Api\r\n{\r\n\t\/**\r\n\t * Returns list of best selling products, returned list is limited to the number items specified in argument.\r\n\t * @param int $limit\r\n\t *\/\r\n\tpublic function getBestsellers($limit=5)\r\n\t{\r\n\t\t\/\/filter\r\n\t\t$visibility = array(\r\n\t\t\t\t\t Mage_Catalog_Model_Product_Visibility::VISIBILITY_BOTH,\r\n\t\t\t\t\t Mage_Catalog_Model_Product_Visibility::VISIBILITY_IN_CATALOG\r\n\t\t\t\t );\r\n\t\t\r\n\t\t$_arrayOfBestsellers = Mage::getResourceModel('reports\/product_collection')\r\n\t\t\t\t\t\t\t\t\t->addAttributeToSelect('*')\r\n\t\t\t\t\t\t\t\t\t->addOrderedQty()\r\n\t\t\t\t\t\t\t\t\t->addAttributeToFilter('visibility', $visibility)\r\n\t\t\t\t\t\t\t\t\t->setOrder('ordered_qty', 'desc')\r\n\t\t\t\t\t\t\t\t\t->getSelect()->limit($limit)->query();\r\n\t\t$bestProducts = array();\r\n\t\t\r\n\t\t$details = Mage::getModel('catalog\/product');\r\n\t\t\r\n\t\tforeach ($_arrayOfBestsellers as $product)\r\n\t\t{\r\n\t\t\t$details->load($product['entity_id']);\r\n\t\t\t$bestProduct[] = array(\r\n\t\t\t\t\t\t\t\t "qty" => $product["ordered_qty"]\r\n\t\t\t\t\t\t\t\t, "price" => $details->getPrice()\r\n\t\t\t\t\t\t\t\t, "name" => $details->getName()\r\n\t\t\t\t\t\t\t\t);\r\n\t\t}\r\n\t\t\r\n\t\treturn $bestProduct;\r\n\t}\r\n\t\/**\r\n\t * Get sales totals\r\n\t * Returns totals for : Revenue, Tax, Shipping and Quantity for given time range, default is last 24 hours.\r\n\t * @param String $period - default '24h', possible values are: 24h, ,1y, 2y\r\n\t *\/\r\n\tpublic function getTotals($period='24h')\r\n\t{\r\n\t\t\r\n $collection = Mage::getResourceModel('reports\/order_collection')\r\n ->addCreateAtPeriodFilter($period)\r\n\t\t\t\/\/->getSelectCountSql()\r\n ->calculateTotals(1)\r\n\t\t\t;\r\n\t\t\/*\r\n\t\t$collection->addFieldToFilter('store_id',\r\n\t\t\tarray('eq' => Mage::app()->getStore(Mage_Core_Model_Store::ADMIN_CODE)->getId())\r\n\t\t);\r\n\t\t*\/\r\n $collection->load();\r\n\t\t\r\n $totals = $collection->getFirstItem();\r\n\t\t\r\n\t\t\r\n\t\treturn array(\r\n\t\t\t\t\t\t 'Revenue' => $totals->getRevenue()\r\n\t\t\t\t\t\t, 'Tax' => $totals->getTax()\r\n\t\t\t\t\t\t, 'Shipping' => $totals->getShipping()\r\n\t\t\t\t\t\t, 'Quantity' => $totals->getQuantity() * 1\r\n\t\t\t\t\t\t);\r\n\t}\r\n}\r\n?>\r\n<\/pre>\nLast bit is the helper class:<\/p>\n
\r\n<!-- magento\/app\/code\/community\/GrelaDesign\/Tutorial\/Helper\/Data.php -->\r\n<?php\r\nclass GrelaDesign_Tutorial_Helper_Data extends Mage_Core_Helper_Abstract\r\n{\r\n\t\r\n}\r\n?>\r\n<\/pre>\nOk that is all for this, lets test:<\/p>\n
log in to the magento admin area, and create 2 rules: “owner” and “client”, for first select all available resources (click on “greladesign”) for second we need to give only access to the essential methods (click on “Core functionality required by all users.”). When you have created those rules, create 2 users and assign those rules to them, i.e.<\/p>\n
rule: “owner”
\nuser: admin
\npass: 1admin<\/p>\nrule: “client”
\nuser: johndoe
\npass: j0hn<\/p>\nonce this is done, create test.php file in the root of your magento folder and past the following:
\nthanks to snippi.net<\/a> I can share with you this test file:)<\/p>\n\r\n<?php\r\n\/*\r\nCreate a file called, 'test.php' in the root of your Magento development environment.\r\nCopy the code below into your test.php file.\r\nBrowse to http:\/\/yourstore\/test.php.\r\n*\/\r\n\r\n\/\/ Tell this file to use the Mage libraries\r\n$mageFilename = 'app\/Mage.php';\r\nrequire_once $mageFilename;\r\numask(0);\r\n\r\n\/\/ Note we are using the 'app' directive not the 'run' directive here\r\n\/\/ Also note the store is named 'default' by, well, default. But as Zeke pointed out if your store is\r\n\/\/ 'en' then you would need to edit the following line to say Mage::app('en')\r\n\/\/ Let's go with 'default' for simplicity ...\r\nMage::app('default');\r\n\r\n\/\/ Your test code goes here\r\n\r\n\techo "<pre>";\r\n\r\n$client = new Zend_XmlRpc_Client('http:\/\/127.0.0.1\/magento\/api\/xmlrpc\/');\r\n\r\n\/\/ If some stuff requires api authentication,\r\n\r\n\/\/ we should get session token\r\n\/\/login\t\r\n\t$session = $client->call('login', array('admin', '1admin'));\r\n\r\n\techo var_dump($client->call('call', array($session, 'tutorial_dashboard.getBestsellers'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'dashboard.getBestsellers'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'tutorial_dashboard.getSalesTotals'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'dashboard.getSalesTotals'))), "\\n";\r\n\t\r\n\techo var_dump($client->call('call', array($session, 'tutorial_core.getVersion'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'core.getVersion'))), "\\n";\r\n\/\/logout\r\n\techo $client->call('endSession', array($session)), "\\n";\r\n\r\n\/\/login\t\r\n\t$session = $client->call('login', array('johndoe', 'j0hn'));\r\n\r\n\techo var_dump($client->call('call', array($session, 'tutorial_dashboard.getBestsellers'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'dashboard.getBestsellers'))), "\\n";\r\n\ttry {\r\n\t\t\/\/this will throw an exception ("access denied")\r\n\t\techo var_dump($client->call('call', array($session, 'tutorial_dashboard.getSalesTotals'))), "\\n";\r\n\t\techo var_dump($client->call('call', array($session, 'dashboard.getSalesTotals'))), "\\n";\r\n\t} catch (Exception $e) {\r\n\t\techo $e->getMessage(), "\\n";\r\n\t}\r\n\t\r\n\techo var_dump($client->call('call', array($session, 'tutorial_core.getVersion'))), "\\n";\r\n\techo var_dump($client->call('call', array($session, 'core.getVersion'))), "\\n";\r\n\/\/logout\r\n\techo $client->call('endSession', array($session)), "\\n";\r\n\r\n\techo "<\/pre>";\r\n\r\n\r\n\r\n?>\r\n<\/pre>\nI hope you will find it useful in any way,
\nhappy coding<\/p>\n","protected":false},"excerpt":{"rendered":"It is not in-depth tutorial but description on how I tackled creation of custom API for magento. There are still vast fields of unknown but at least this will let you start building your own API and let you learn, … Continue reading