Skip to content
intermediate Phase 21 · Module Configuration Files

webapi.xml - Module Configuration Files

Understanding Magento 2 webapi.xml: REST routes, SOAP services, method definitions, service classes, and ACL resource authorization

45m
0 problems
Topic Progress 0%

webapi.xml Overview

What is webapi.xml?

The webapi.xml file defines API endpoints for both REST and SOAP interfaces. Unlike routes.xml which maps URLs to controllers, webapi.xml maps HTTP routes directly to service contract interfaces — no controller layer needed.

File Location

Vendor/Module/etc/webapi.xml

Basic Structure

<?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 method="GET" url="/V1/products/:sku">
        <service class="Magento\Catalog\Api\ProductRepositoryInterface" method="get"/>
        <resources>
            <resource ref="Magento_Catalog::products"/>
        </resources>
    </route>
</routes>

Key Differences from routes.xml

Aspect routes.xml webapi.xml
Handles Web pages API requests
Maps to Controllers Service interfaces
Supports HTML, AJAX REST, SOAP
Auth Session/Cookie Token/OAuth

Route Method Attributes

Attribute Description
method HTTP method: GET, POST, PUT, DELETE
url Route URL pattern with :param placeholders
service class Fully qualified interface name
service method Method on the interface to call
resources ref ACL resource for authorization

REST Route Patterns

URL Parameters

Use colon prefix for route parameters:

<!-- Single parameter -->
<route method="GET" url="/V1/products/:sku">
    <service class="Magento\Catalog\Api\ProductRepositoryInterface" method="get"/>
    <resources>
        <resource ref="Magento_Catalog::products"/>
    </resources>
</route>

<!-- Multiple parameters -->
<route method="GET" url="/V1/customers/:customerId/addresses/:addressId">
    <service class="Magento\Customer\Api\AddressRepositoryInterface" method="getById"/>
    <resources>
        <resource ref="Magento_Customer::manage"/>
    </resources>
</route>

HTTP Methods

<!-- GET: Retrieve data -->
<route method="GET" url="/V1/categories/:categoryId">
    <service class="Magento\Catalog\Api\CategoryRepositoryInterface" method="get"/>
</route>

<!-- POST: Create new resource -->
<route method="POST" url="/V1/categories">
    <service class="Magento\Catalog\Api\CategoryRepositoryInterface" method="save"/>
</route>

<!-- PUT: Update existing resource -->
<route method="PUT" url="/V1/categories/:categoryId">
    <service class="Magento\Catalog\Api\CategoryRepositoryInterface" method="save"/>
</route>

<!-- DELETE: Remove resource -->
<route method="DELETE" url="/V1/categories/:categoryId">
    <service class="Magento\Catalog\Api\CategoryRepositoryInterface" method="deleteByIdentifier"/>
</route>

Search Criteria for Lists

<route method="GET" url="/V1/products">
    <service class="Magento\Catalog\Api\ProductRepositoryInterface" method="getList"/>
    <resources>
        <resource ref="Magento_Catalog::products"/>
    </resources>
</route>

The GET endpoint accepts query parameters for filtering:

GET /rest/V1/products?searchCriteria[filter_groups][0][filters][0][field]=name&searchCriteria[filter_groups][0][filters][0][value]=Widget

Empty URL for Collection Endpoints

When the URL has no parameters, the route URL is just the base path:

<route method="POST" url="/V1/wishlist/items">
    <service class="Magento\Wishlist\Api\ItemRepositoryInterface" method="save"/>
</route>

SOAP vs REST

SOAP Services

SOAP uses WSDL (Web Services Description Language) to define services. In Magento, SOAP operations are derived from the same webapi.xml configuration.

A SOAP client can call:

$client = new SoapClient('http://magento.soap.wsdl');
$result = $client->catalogProductRepositoryGet(['sku' => 'ABC']);

REST Calls

Same endpoint, different interface:

curl -X GET http://magento/rest/V1/products/ABC \
     -H 'Authorization: Bearer TOKEN'

Key Differences

Feature REST SOAP
Format JSON XML
Schema No WSDL needed WSDL required
Methods Standard HTTP verbs Any method via POST
Complexity Simpler More structured
Magento support Primary focus Supported but less common

SOAP-Specific Configuration

SOAP operations follow the pattern:

{interfaceShortName}{methodName}

For Magento\Catalog\Api\ProductRepositoryInterface::get:

  • SOAP operation: catalogProductRepositoryGet
  • SOAP call: $client->catalogProductRepositoryGet(['sku' => 'ABC'])

Service Class References

The service class attribute must reference a service contract interface:

<!-- Correct: uses interface -->
<service class="Magento\Catalog\Api\ProductRepositoryInterface" method="get"/>

<!-- Incorrect: uses implementation -->
<service class="Magento\Catalog\Model\ProductRepository" method="get"/>

Always reference the interface. The ObjectManager resolves the actual implementation via di.xml preferences.

ACL Resources and Authorization

ACL Resource References

Every API route needs an ACL resource for authorization:

<route method="GET" url="/V1/products/:sku">
    <service class="Magento\Catalog\Api\ProductRepositoryInterface" method="get"/>
    <resources>
        <resource ref="Magento_Catalog::products"/>
    </resources>
</route>

No Auth Required

For public endpoints, use anonymous access:

<route method="GET" url="/V1/store/storeConfigs">
    <service class="Magento\Store\Api\StoreConfigManagerInterface" method="getStoreConfigs"/>
    <resources>
        <resource ref="anonymous"/>
    </resources>
</route>

Self Access

Allow users to access their own resources:

<route method="GET" url="/V1/customers/me">
    <service class="Magento\Customer\Api\CustomerRepositoryInterface" method="getById"/>
    <resources>
        <resource ref="Magento_Customer::manage"/>
    </resources>
</route>

Admin-Only Resources

Restrict to admin users:

<route method="POST" url="/V1/cms/page">
    <service class="Magento\Cms\Api\PageRepositoryInterface" method="save"/>
    <resources>
        <resource ref="Magento_Cms::pages"/>
    </resources>
</route>

Defining Custom ACL Resources

In etc/acl.xml:

<config>
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::stores">
                    <resource id="Vendor_Module::api_access"
                              title="Vendor Module API Access"
                              sortOrder="100"/>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

Then reference it in webapi.xml:

<resources>
    <resource ref="Vendor_Module::api_access"/>
</resources>

Complete Custom Module Example

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    
    <!-- GET /rest/V1/vendor-warranty/:id -->
    <route method="GET" url="/V1/vendor-warranty/:id">
        <service class="Vendor\Warranty\Api\WarrantyRepositoryInterface" method="get"/>
        <resources>
            <resource ref="Vendor_Warranty::view"/>
        </resources>
    </route>
    
    <!-- POST /rest/V1/vendor-warranty -->
    <route method="POST" url="/V1/vendor-warranty">
        <service class="Vendor\Warranty\Api\WarrantyRepositoryInterface" method="save"/>
        <resources>
            <resource ref="Vendor_Warranty::manage"/>
        </resources>
    </route>
    
    <!-- GET /rest/V1/vendor-warranty/search -->
    <route method="GET" url="/V1/vendor-warranty/search">
        <service class="Vendor\Warranty\Api\WarrantyRepositoryInterface" method="getList"/>
        <resources>
            <resource ref="Vendor_Warranty::view"/>
        </resources>
    </route>
    
</routes>

Quiz

1. How do you define a parameter in a webapi.xml route URL?

Question 1 options

2. What should the service class attribute reference in webapi.xml?

Question 2 options

3. Which ACL resource allows anonymous (unauthenticated) API access?

Question 3 options

Flashcards

Question

What does webapi.xml configure?

Click to reveal answer

Answer

REST and SOAP API endpoints, mapping routes to service contract interfaces

Question

How do route parameters work in webapi.xml?

Click to reveal answer

Answer

Use colon prefix: :sku, :categoryId, etc.

Question

What is the difference between webapi.xml and routes.xml?

Click to reveal answer

Answer

webapi.xml maps to service interfaces (API), routes.xml maps to controllers (web pages)

Question

How do you make an API endpoint public?

Click to reveal answer

Answer

Use resource ref='anonymous' in the resources section

Question

What format does SOAP use for operations?

Click to reveal answer

Answer

InterfaceShortName + MethodName (e.g., catalogProductRepositoryGet)

Revision Notes

Key Takeaways

  • 1. webapi.xml defines REST/SOAP endpoints mapped to service contract interfaces
  • 2. Route parameters use colon prefix (:param)
  • 3. Always reference interfaces, not implementations, in service class
  • 4. Use 'anonymous' for public endpoints, specific ACL resources for protected ones
  • 5. SOAP operations follow the pattern: interfaceShortName + methodName

Interview Tips

  • • Explain how webapi.xml differs from routes.xml
  • • Know the REST HTTP method conventions (GET=read, POST=create, PUT=update, DELETE=remove)
  • • Understand how ACL resources control API access
  • • Be ready to discuss search criteria for collection endpoints

Cheat Sheet

<route method="GET" url="/V1/products/:sku">
  <service class="Vendor\Module\Api\RepositoryInterface" method="get"/>
  <resources>
    <resource ref="Vendor_Module::access"/>
  </resources>
</route>

Public: resource ref="anonymous"
SOAP op: InterfaceName + MethodName