Skip to main content

Magento 2 API – Beginners Guide for API development

 Magento 2 API – Today we are going to learn how to create rest based API for Magento 2.

I have worked on Magento 1 and found it very difficult to create a rest webAPI.

But as I was expecting Magento 2 has a very easy way to define your API resources for the module, specially defining routes for Magento API integration.

Also, check how to create GraphQL API in Adobe Commerce

To create a rest API there are some certain requirements for Magento API integration :

  • you need to create an interface in your module’s API folder.
  • then you need to define all the API methods that you want to expose to the web in the interface.
  • all the methods should have a doc-block.
  • in the doc-block @api must be defined
  • if your method expects parameters than all the parameters must be defined in the doc-block as @params <type> <param> <description>
  • return type of the method must be defined as @return <type> <description>
  • concrete class of the method must be defined and it should give the definition of all the API methods and should inherit the doc-block.

If your API method do not met any of the above requirements then rest API will not work for magento 2 integration API.

Now, for an example lets create a test module named Webkul_TestApi for better understanding :

create your module composer.json, registration.php and module.xml files:

<?php
/**
* Webkul Software.
*
* @category Webkul_MpApi
*
* @author Webkul
* @copyright Copyright (c) Webkul Software Private Limited (https://webkul.com)
* @license https://store.webkul.com/license.html
*/
\Magento\Framework\Component\ComponentRegistrar::register(
\Magento\Framework\Component\ComponentRegistrar::MODULE,
'Webkul_TestApi',
__DIR__
);
Explain Code
Powered By
{
"name": "webkul/marketplace-api",
"description": "Marketplace api for magento2",
"require": {
"php": "~5.5.0|~5.6.0|~7.0.0",
"magento/module-config": "100.0.*",
"magento/module-store": "100.0.*",
"magento/module-checkout": "100.0.*",
"magento/module-catalog": "100.0.*",
"magento/module-sales": "100.0.*",
"magento/module-customer": "100.0.*",
"magento/module-payment": "100.0.*",
"magento/module-quote": "100.0.*",
"magento/module-backend": "100.0.*",
"magento/module-directory": "100.0.*",
"magento/module-theme": "100.0.*",
"magento/framework": "100.0.*"
},
"type": "magento2-module",
"version": "2.0.0",
"license": [
"proprietary"
],
"autoload": {
"files": [
"registration.php"
],
"psr-4": {
"Webkul\\TestApi\\": ""
}
}
}
Explain Code
Powered By
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
<module name="Webkul_TestApi" />
</config>
Explain Code
Powered By

Now create TestApiManagementInterface.php file in app/code/Webkul/TestApi/Api/ folder:

<?php
namespace Webkul\TestApi\Api;
interface TestApiManagementInterface
{
/**
* get test Api data.
*
* @api
*
* @param int $id
*
* @return \Webkul\TestApi\Api\Data\TestApiInterface
*/
public function getApiData($id);
}
Explain Code
Powered By

the above will define all the api methods you want to expose, all these methods must have doc-block defined with @api, @param and @return else it will not work for Magento 2 integration API.

Now create TestApiManagementInterface implementation file in app/code/Webkul/TestApi/Model/Api folder:

<?php
namespace Webkul\TestApi\Model\Api;
class TestApiManagement implements \Webkul\TestApi\Api\TestApiManagementInterface
{
const SEVERE_ERROR = 0;
const SUCCESS = 1;
const LOCAL_ERROR = 2;
protected $_testApiFactory;
public function __construct(
\Webkul\TestApi\Model\TestApiFactory $testApiFactory
) {
$this->_testApiFactory = $testApiFactory;
}
/**
* get test Api data.
*
* @api
*
* @param int $id
*
* @return \Webkul\TestApi\Api\Data\TestApiInterface
*/
public function getApiData($id)
{
try {
$model = $this->_testApiFactory
->create();
if (!$model->getId()) {
throw new \Magento\Framework\Exception\LocalizedException(
__('no data found')
);
}
return $model;
} catch (\Magento\Framework\Exception\LocalizedException $e) {
$returnArray['error'] = $e->getMessage();
$returnArray['status'] = 0;
$this->getJsonResponse(
$returnArray
);
} catch (\Exception $e) {
$this->createLog($e);
$returnArray['error'] = __('unable to process request');
$returnArray['status'] = 2;
$this->getJsonResponse(
$returnArray
);
}
}
}
Explain Code
Powered By

the above class is the implementation of the interface as you can see I have only created one method getApiData as it is defined in the interface its return type is \Webkul\TestApi\Api\Data\TestApiInterface class

So now we have to create this class and its implementation too for api for magento 2.

Now create a model TestApi.php inside app/code/Webkul/TestApi/Model, this is a fake model it is not connected to any table since its only for testing purpose, I have just defined some setters and getters for some fields.

<?php
namespace Webkul\TestApi\Model;
/**
* Marketplace Product Model.
*
* @method \Webkul\Marketplace\Model\ResourceModel\Product _getResource()
* @method \Webkul\Marketplace\Model\ResourceModel\Product getResource()
*/
class TestApi implements \Webkul\TestApi\Api\Data\TestApiInterface
{
/**
* Get ID.
*
* @return int
*/
public function getId()
{
return 10;
}
/**
* Set ID.
*
* @param int $id
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setId($id)
{
}
/**
* Get title.
*
* @return string|null
*/
public function getTitle()
{
return 'this is test title';
}
/**
* Set title.
*
* @param string $title
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setTitle($title)
{
}
/**
* Get desc.
*
* @return string|null
*/
public function getDescription()
{
return 'this is test api description';
}
/**
* Set Desc.
*
* @param string $desc
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setDescription($desc)
{
}
}
Explain Code
Powered By

the above class has getTitle, getDescription and getId so we must expect that api for magento 2 will return these values in the response.

Now create the interface class for the above implementation in app/code/Webkul/TestApi/Api/Data.

<?php
/**
* Webkul Software.
*
* @category Webkul
*
* @author Webkul
* @copyright Copyright (c) Webkul Software Private Limited (https://webkul.com)
* @license https://store.webkul.com/license.html
*/
namespace Webkul\TestApi\Api\Data;
/**
* Marketplace product interface.
*
* @api
*/
interface TestApiInterface
{
/**#@+
* Constants for keys of data array. Identical to the name of the getter in snake case
*/
const ENTITY_ID = 'entity_id';
const TITLE = 'title';
const DESC = 'description';
/**#@-*/
/**
* Get ID.
*
* @return int|null
*/
public function getId();
/**
* Set ID.
*
* @param int $id
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setId($id);
/**
* Get title.
*
* @return string|null
*/
public function getTitle();
/**
* Set title.
*
* @param string $title
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setTitle($title);
/**
* Get desc.
*
* @return string|null
*/
public function getDescription();
/**
* Set Desc.
*
* @param string $desc
*
* @return \Webkul\Marketplace\Api\Data\ProductInterface
*/
public function setDescription($desc);
}
Explain Code
Powered By

Now You need to create “app/code/Webkul/TestApi/etc/di.xml” file to map interfaces with the concrete classes:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<preference for="Webkul\TestApi\Api\TestApiManagementInterface" type="Webkul\TestApi\Model\Api\TestApiManagement" />
<preference for="Webkul\TestApi\Api\Data\TestApiInterface" type="Webkul\TestApi\Model\TestApi" />
</config>
Explain Code
Powered By

Now create a webapi.xml file inside app/code/Webkul/TestApi/etc folder:

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
<!-- test api Group -->
<route url="/V1/testapi/custom/me" method="GET">
<service class="Webkul\TestApi\Api\TestApiManagementInterface" method="getApiData"/>
<resources>
<resource ref="self"/>
</resources>
<data>
<parameter name="id" force="true">%customer_id%</parameter>
</data>
</route>
</routes>
Explain Code
Powered By

the above xml file defines the routes and their permissions.
The route tag attributes:

  • attribute url defines the route for the web service
  • attribute method defines the request type GET,PUT,POST or DELETE

Now the service tag attributes:

  • class attribute is the interface class that defines the api methods.
  •  service attribute defines the exposed method

now the resource tag defines the access control these can be three level of access:

  •  Admin : for admin level access you need to define admin resource in the resource tag.
  • Customer: for customer level access you need to set self in the resource.
  • Guest: for guest level resources you need to define anonymous in the resource tag.
  • I have defined self so this resource will work for customer level access.

Originally Published: https://webkul.com/blog/magento2-custom-rest-api/
Labels:

Comments

Post a Comment

Popular posts from this blog

Warehouse Management System (WMS) Mobile App for Magento 2

  Introduction Magento 2 Warehouse Management System Mobile App provides the mobile app to the warehouse staff to manage the orders that arrived for delivery at the warehouse. It is a  Magento 2 Inventory Management software  app that helps the admin to manage the warehouse very easily. Also, it allows the admin to manage the product assigned in the sources warehouse. For each source in the Magento MSI feature, a warehouse can be assigned. Also, the admin can define its structure (number of rows, columns, Shelves Per Cluster, and racks per shelf). The Admin has the feature to assign the product to the racks available in the warehouse. The admin can assign the products of an order to the different warehouses and their staff. The staff of the warehouse can easily manage the orders assigned to them by the admin through the WMS app. Likewise, Magento 2 Inventory Management software, the admin can even create multiple warehouses for this mobile app. Moreover, the app follows t...
Post a Comment
Read more

Point Of Sale System For Magento

  It refers to a system where the merchant can create the order from his physical store using the POS and the order will be generated in the Magento. The Basic feature of the POS system for Magento is to create the order in front of the customer so that customer can purchase the goods from his/her physical store as well as from his/her online eCommerce store . With the help of this module, merchants can manage their inventory and customers. And the most important thing is that they can easily manage their day-to-day transactions without any hassle. This module is a powerful tool to manage the sales and revenue. Admin can also set up the physical store along with the online Magento store. Please Note- ·          The Magento POS connects only to the Printer, and barcode reader, whereas it doesn't connect directly with the cash drawer and card swapping machine. ·          POS requires a browser to ...
Post a Comment
Read more

Top 5 Channel Manager Features You Need To Use

 Have you ever wondered, what makes your hotel business successful? Can it be the competitive pricing or exotic location for the hotel? Well, all these are crucial contributing factors for your hotel success but, one of the major factors that contributes more than others is the visibility of your hotel. Travelers today are getting more tech-savvy and rely on various OTA to look for a stay for their vacation. So, it becomes necessary for your guests to be able to find you.  You might be using a hotel channel manager to manage your listings of various OTAs. However, There’s still a chance that your guest might miss your hotel on the OTAs. So, in this blogpost we will discuss the top 5 hotel channel manager features you need to use to enhance your business. What is the need for a hotel channel manager? In your hotel you might get bookings through walk-ins or by phone call. The guests can also make the booking through your hotel website or there’s a good chance that ...
Post a Comment
Read more