Configure services as web APIs

Overview

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 webapi.xml file for your module specifies an XML schema file for validation. By default, this file is app/code/<VENDOR>/Webapi/etc/webapi.xsd.

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
webapi.xml configuration options
Sample webapi.xml file
webapi.xsd XML schema file

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:

XML element	Description	Attributes
`<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. Magento resource. Optionally, one or more template parameters. `secure`. Optional. Boolean. Indicates that the route is accessible over only HTTPS. Any attempts to access this route over non-secure causes an exception.
`<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 Magento resource, such as `Magento_Customer::group`. Note:The Magento 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.	`name`. String. Parameter name. `force`. Boolean.

Sample webapi.xml file

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

In this webapi.xml example:

Line	Defines
3	The 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`.
5	The 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.
6	The 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 `get`.
8	The resource to which the caller must have access. The caller must have access to `Magento_Customer::group` resource.
18	A 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.

Thanks to Classy Llama for contributing this topic

Edit this page on GitHub

Give us feedback