Configure services as web APIs

You can configure a Magento or third-party service as a web API.

To configure a web API, you define XML elements and attributes in the webapi.xml XML configuration file for the module for the service. The etc/webapi.xsd file for your module specifies an XML schema file for validation. The default XML schema validation rules are stored in app/code/Magento/Webapi/etc/webapi.xsd or vendor/magento/module-webapi/etc/webapi.xsd file.

Your module can use the default webapi.xsd file or you can create a customized XML schema file for validation.

Users can make REST or SOAP calls to access the web API.

To configure a web API, read these topics:

• Configure a web API
• Service Interface Requirements
• webapi.xml configuration options
• Sample webapi.xml file
• webapi.xsd XML schema file
• Forcing Request Parameters

Configure a web API

To configure a web API for a service, you define XML elements and attributes in the app/code/Magento/<MODULE>/etc/webapi.xml file, where <MODULE> is the module name. For example, the web API for the Customer service is defined in the app/code/Magento/Customer/etc/webapi.xml configuration file.

Service Interface Requirements

After a service class is configured using the webapi.xml file, Magento dynamically makes the service method available using the web API. Because this is automatically generated, it is important that the service class be formatted a very specific way.

This makes sense when you consider that while a service class possibly expects objects of a specific class type (such a save method) and possibly returns a result that is a class or array of classes, neither SOAP nor REST are guaranteed to have that class defined on the client end or even to have a concept similar to a PHP class. Because of this, Magento uses reflection to automatically create these classes and sets data that you have submitted in JSON or HTTP array syntax onto an instance of the expected PHP class when calling the service method.

Conversely, if an object is returned from one of these methods, Magento automatically converts that PHP object into a JSON or SOAP object before sending it over the web API.

To do this conversion, the Magento application must know information about both the parameters the service method is expecting and the return type of the result the service method delivers. PHP 5.x does not allow for type-hinting for scalar parameters or for return types so in order to convert the array or JSON object to or from the appropriate class type, PHP relies on the PHP doc block. Specifically, the lines containing @param and @return must follow certain rules for Magento to be able to correctly convert between types.

For SOAP and REST to work correctly, the following rules must be followed by the service interface’s doc block:

• All methods exposed by the web API must follow these rules
• All methods on objects expected as parameters or returned must follow these rules

• Parameters must be defined in the doc block as

  • @param type $paramName

• Return type must be defined in the doc block as

  • @return type
• Valid scalar types include: mixed (or anyType), bool (or boolean), str (or string), integer (or int), float, and double.
• Valid object types include a fully qualified class name or a fully qualified interface name.
• Any parameters or return values of type array can be denoted by following any of the previous types by an empty set of square brackets []

Following are some examples of various types and what they would look like in the doc block:

• A parameter $types which can be an array of strings:

  • @param string[] $types

• A parameter $id which can be an integer:

  • @param int $id

• A parameter $customer which is an object of class \Magento\Customer\Api\Data\CustomerInterface:

  • @param \Magento\Customer\Api\Data\CustomerInterface $customer

    Note that even if the class \Magento\Customer\Api\Data\CustomerInterface is in the same namespace (or a sub-namespace) of the current class or a use statement has exists at the top of the class, the fully qualified namespace must be used or the web API throws an exception.

• A return which is an array of objects of type \Magento\Customer\Api\Data\CustomerInterface:

  • @return \Magento\Customer\Api\Data\CustomerInterface[]

If a service method argument is called item, there will be a problem during SOAP processing. All item nodes are removed during SOAP request processing. This is done to unwrap array items that are wrapped by the SOAP server into an item element.

webapi.xml configuration options

To define web API components, set these attributes on these XML elements in the webapi.xml configuration file, as follows:

Sample webapi.xml file

This excerpt is from the webapi.xml file that defines the Customer service web API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?xml version="1.0"?>
    <routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <!-- Customer Group Service-->
    <route url="/V1/customerGroups/:id" method="GET">
        <service class="Magento\Customer\Api\GroupRepositoryInterface" method="getById"/>
        <resources>
            <resource ref="Magento_Customer::group"/>
        </resources>
    </route>
...
    <route url="/V1/customers/me/billingAddress" method="GET">
        <service class="Magento\Customer\Api\AccountManagementInterface" method="getDefaultBillingAddress"/>
        <resources>
            <resource ref="self"/>
        </resources>
        <data>
            <parameter name="customerId" force="true">%customer_id%</parameter>
        </data>
    </route>
</routes>

In this webapi.xml example:

webapi.xsd XML schema file

The webapi.xml file for your module must specify an XML schema file for validation. Your webapi.xml file can specify the default or a customized XML schema file. The default webapi.xsd XML schema file can be found in the app/code/Magento/Webapi/etc directory.

The following table defines the service node attributes:

Forcing Request Parameters

Parameters in the webapi.xml can be forced. This ensures that on specific routes, a specific value is always used. For instance, in the example “/V1/customers/me/billingAddress” route above, the customerId parameter is forced to match the ID of the currently logged in user. Additional parameter overrides can be registered via di.xml by adding new items to the paramOverriders argument for \Magento\Webapi\Controller\Rest\ParamsOverrider. Parameter overriders must implement \Magento\Framework\Webapi\Rest\Request\ParamOverriderInterface. An example excerpt from di.xml

1
2
3
4
5
6
7
<type name="Magento\Webapi\Controller\Rest\ParamsOverrider">
    <arguments>
        <argument name="paramOverriders" xsi:type="array">
            <item name="%my_value%" xsi:type="object">VENDOR\MODULE\Controller\Rest\ParamOverriderMyValue</item>
        </argument>
    </arguments>
</type>

The above example create a new parameter override available for use in webapi.xml. The value passed for %my_value% will be the return value of \VENDOR\MODULE\Controller\Rest\ParamOverriderMyValue::getOverriddenValue. Example:

1
2
3
4
5
6
7
<route url="/V1/example/me/service" method="GET">
    ...
    <data>
        <parameter name="myValue" force="true">%my_value%</parameter>
    </data>
    ...
</route>