Basics to webapi REST in Magento 2

Today, we are going to learn how to create a REST api in Magento 2.

As there are so many configurations files available in Magento 2, serve different purposes, we must have heard about webapi.xml . This is the file which we used to define our api route. Magento also has a seperate area called webapi_rest to handle configurations of REST apis.

So, we have to define our api in etc/webapi.xml .

<?xml version="1.0"?>

<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/external/order" method="POST">
        <service class="Vishesh\ExternalOrder\Api\ExternalOrderRepositoryInterface" method="create"/>
        <resources>
            <resource ref="Vishesh_ExternalOrder::external_orders" />
        </resources>
    </route>
</routes>

• Route Url - This defines the api url like https://{{magento_base_url}}/V1/external/order

• Method - This defines the method for our api (GET, POST, PUT, DELETE)

• Service class - This defines our api class namespace which contains the logic of our api

• Service method - This is the method name which you want to execute when api called

• Resource - This paramater is used to define the access level of the api, it can the any resource name, anonymous and self.

Now, we have to define our api interface and its implementation to make our api work.

Api\ExternalOrderRepositoryInterface.php

<?php
namespace Vishesh\ExternalOrder\Api;

/**
 * External Order repository interface.
 *
 * @api
 */
interface ExternalOrderRepositoryInterface
{
    /**
     * Creates new external order
     *
     * @param mixed $payload
     * @return \Vishesh\ExternalOrder\Api\Data\ExternalOrderInterface
     */
    public function create($payload);
}

**Method signatures played an important role while working with webapi. Magento uses the method signatures for type checking of api parameters and response.

Here we are using mixed type so that we can pass multiple data type values in the payload. Parameter's type checking is strict means parameter type must match with one that is mentioned in the interface.

As here we passed an interface class as return type for our method, so if we return response of array type or string type, it neither throw any error nor checks the response type, it will work fine. For example, if we return -

 $response = [[
       'status' => true,
       'increment_id' => $order->getIncrementId()
  ]];
  return $response;

Then it will return following response -

But if response is of Object type then it will match the response with the defined return class interface, and create response accordingly. For example, if we return -

return $order;

Then it will return only those fields which are defined in the mentioned interface class like -

Now, we have to create a class which implements the defined inerface and contain its logic.

Model\ExternalOrderRepository.php

etc/di.xml

One more thing to keep in mind is that, the variable name which we are passing in the service method as parameter must be present in the request body as key. E.g., here we are passing $payload to our service method, so we must have payload key present in request json like -

{
    "payload": {
        //Request json
    }
}

This is how we can create a REST api in Magento 2.

Happy Coding :)