Edit in GitHubLog an issue
Thanks to Classy Llama for contributing this topic!

Configure services as web APIs

You can configure an Adobe Commerce, Magento Open Source, 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#

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, the application 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, the application 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, the application automatically converts that PHP object into a JSON or SOAP object before sending it over the web API.

To do this conversion, the 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 the application 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[]

webapi.xml configuration options#

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

XML elementDescriptionAttributes
<routes>Required. Root element that defines the namespace and location of the XML schema file.
  • xmlns:xsi. Required. Defines the namespace for the XML schema instance.
  • xsi:noNamespaceSchemaLocation. Required. Defines the path and file name of the XML schema file to use to validate the web API.
<route>Required. Child element of <routes>. Defines the HTTP route for the web API method.
  • method. Required. String. HTTP method. Valid values are GET, POST, PUT, and DELETE.
  • url. Required. String. The URL to the resource. The string must begin with /V1 (or <integer>) to indicate the version number. You must prepend any template parameters with a colon. Example: /V1/products/:sku
  • secure. Optional. Boolean. Indicates that the route is accessible over only HTTPS. Any attempts to access this route over non-secure causes an exception.
  • soapOperation. Optional. String. Specifies the SOAP operation name to use instead of the interface's method name. Use this element to create multiple operations for the same service contract.
<service>Required. Child element of <route>. Defines the implemented interface and the web API method name.
  • class. Required. String. Location and name of implemented interface.
  • method. Required. String. Web API method name.
<resources>Required. Child element of <route>. Container for one or more resource definitions.None.
<resource>Required. Child element of <resources>. Defines a resource to which the caller must have access.
  • ref. Required. Referenced resource. Valid values are self, anonymous, or a resource, such as Magento_Customer::group.Note: The web API framework enables guest users to access resources that are configured with anonymous permission. Any user that the framework cannot authenticate through existing authentication mechanisms is considered a guest user.
<data>Optional. Child element of <route>. Container for one or more parameter definitions.None.
<parameter>Required if <data> is specified. Child element of <data>. Defines a parameter.

Sample webapi.xml file#

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

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

In this webapi.xml example:

LineDefines
2The XML schema file that is used to validate the XML. The XML schema file is xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd.
4The HTTP method and web resource through which to access the route. The HTTP method is GET. The resource is /V1/customerGroups/:id. Users must substitute a customer ID for the id template parameter.
5The interface that the route implements and the name of the web API method. The route implements the Magento\Customer\Api\GroupRepositoryInterface interface. The web API method name is getById.
7The resource to which the caller must have access. The caller must have access to Magento_Customer::group resource.
17A required parameter. The id parameter is required on GET calls to /V1/customers/me/billingAddress.

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:

Attribute nameRequiredDescription
classYesThe responsible class for handling the API request.
methodYesThe class' method which handles the execution of the API.

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

Copied to your clipboard
1<type name="Magento\Webapi\Controller\Rest\ParamsOverrider">
2 <arguments>
3 <argument name="paramOverriders" xsi:type="array">
4 <item name="%my_value%" xsi:type="object">VENDOR\MODULE\Controller\Rest\ParamOverriderMyValue</item>
5 </argument>
6 </arguments>
7</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:

Copied to your clipboard
1<route url="/V1/example/me/service" method="GET">
2 ...
3 <data>
4 <parameter name="myValue" force="true">%my_value%</parameter>
5 </data>
6 ...
7</route>
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.