Skip to content
intermediate Phase 26 · Module Complete

Setting Up API - Complete Guide

Guide to setting up Magento 2 API: webapi.xml, service contract interfaces, ACL resources, and creating custom REST API endpoints

45m
0 problems
Topic Progress 0%

API Architecture

API Request Flow

REST Request → Router → webapi.xml Match → Service Class → Repository → Resource Model → Database

Service Contract Layers

API Consumer (REST/SOAP)
    ↓
webapi.xml (route definition)
    ↓
Interface (service contract)
    ↓
Repository (implementation)
    ↓
Resource Model (database)

Module API Structure

Amazon/Prep/
├── etc/
│   ├── webapi.xml              (API routes)
│   ├── acl.xml                 (authorization)
│   └── di.xml                  (interface binding)
├── Api/
│   ├── WarrantyRepositoryInterface.php
│   └── Data/
│       └── WarrantyInterface.php
├── Model/
│   ├── Warranty.php
│   ├── WarrantyRepository.php
│   └── ResourceModel/
│       ├── Warranty.php
│       └── Warranty/Collection.php
└── etc/
    └── db_schema.xml

Key Files

File Purpose
webapi.xml Defines API routes
acl.xml Defines authorization resources
di.xml Binds interfaces to implementations
RepositoryInterface CRUD operations
DataInterface Data structure definition

webapi.xml Configuration

Complete 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">

    <!-- GET /rest/V1/warranty/:id -->
    <route method="GET" url="/V1/warranty/:id">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="get"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_view"/>
        </resources>
    </route>

    <!-- GET /rest/V1/warranty (list with search criteria) -->
    <route method="GET" url="/V1/warranty">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="getList"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_view"/>
        </resources>
    </route>

    <!-- POST /rest/V1/warranty (create) -->
    <route method="POST" url="/V1/warranty">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="save"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_manage"/>
        </resources>
    </route>

    <!-- PUT /rest/V1/warranty/:id (update) -->
    <route method="PUT" url="/V1/warranty/:id">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="save"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_manage"/>
        </resources>
    </route>

    <!-- DELETE /rest/V1/warranty/:id -->
    <route method="DELETE" url="/V1/warranty/:id">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="deleteById"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_manage"/>
        </resources>
    </route>

    <!-- GET /rest/V1/warranty/search (search with criteria) -->
    <route method="GET" url="/V1/warranty/search">
        <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="getList"/>
        <resources>
            <resource ref="Amazon_Prep::warranty_view"/>
        </resources>
    </route>

</routes>

URL Parameters

<!-- Single parameter -->
<route method="GET" url="/V1/warranty/:id">

<!-- Multiple parameters -->
<route method="GET" url="/V1/warranty/:warrantyId/product/:productId">

<!-- No parameters (collection) -->
<route method="GET" url="/V1/warranty">

ACL Resources

acl.xml Configuration

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::stores">
                    <resource id="Magento_Backend::stores_settings">
                        <resource id="Magento_Backend::config">
                            <resource id="Amazon_Prep::config"
                                      title="Amazon Prep Configuration"
                                      sortOrder="100"/>
                        </resource>
                    </resource>
                </resource>
                <resource id="Magento_Backend::stores_tools">
                    <resource id="Amazon_Prep::warranty_manage"
                              title="Manage Warranties"
                              sortOrder="100"/>
                    <resource id="Amazon_Prep::warranty_view"
                              title="View Warranties"
                              sortOrder="200"/>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

ACL Hierarchy

Magento_Backend::admin
├── Magento_Backend::stores
│   └── Magento_Backend::stores_settings
│       └── Magento_Backend::config
│           └── Amazon_Prep::config
└── Magento_Backend::stores_tools
    ├── Amazon_Prep::warranty_manage
    └── Amazon_Prep::warranty_view

Anonymous Access

For public endpoints:

<route method="GET" url="/V1/warranty/public">
    <service class="Amazon\Prep\Api\WarrantyRepositoryInterface" method="getList"/>
    <resources>
        <resource ref="anonymous"/>
    </resources>
</route>

Admin-Only Access

Restrict to admin users:

<resources>
    <resource ref="Magento_Backend::admin"/>
</resources>

Testing API Endpoints

Authentication

# Get admin token
curl -X POST http://magento/rest/V1/integration/admin/token \
     -H "Content-Type: application/json" \
     -d '{"username":"admin", "password":"admin123"}'

# Response: "eyJhbGciOiJIUzI1NiJ9..."

# Use token in requests
curl -X GET http://magento/rest/V1/warranty/1 \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Test GET Request

curl -X GET http://magento/rest/V1/warranty/1 \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json"

# Response:
{
    "warranty_id": 1,
    "name": "Premium Warranty",
    "duration": 24,
    "price": 99.99,
    "status": 1,
    "sku": "WARR-PREM-001"
}

Test List Request

curl -X GET "http://magento/rest/V1/warranty?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=1" \
     -H "Authorization: Bearer TOKEN"

# Response:
{
    "items": [...],
    "total_count": 5,
    "search_criteria": {...}
}

Test POST Request

curl -X POST http://magento/rest/V1/warranty \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "name": "New Warranty",
         "duration": 12,
         "price": 49.99,
         "sku": "WARR-NEW-001",
         "status": 1
     }'

# Response:
{
    "warranty_id": 6,
    "name": "New Warranty",
    ...
}

Error Handling

# 401 Unauthorized
curl -X GET http://magento/rest/V1/warranty/1
# {"message":"The consumer isn't authorized to access %1."}

# 404 Not Found
curl -X GET http://magento/rest/V1/warranty/999
# {"message":"No such entity with warrantyId = 999"}

# 400 Bad Request
curl -X POST http://magento/rest/V1/warranty -d '{}'
# {"message":"Invalid input data"}

Swagger Documentation

Magento generates API documentation at:

http://magento/rest/V1/schema

This provides a Swagger/OpenAPI specification for all API endpoints.

Quiz

1. What file defines API routes in Magento?

Question 1 options

2. What ACL resource allows public API access?

Question 2 options

3. How do you get an admin API token?

Question 3 options

Flashcards

Question

What does webapi.xml map?

Click to reveal answer

Answer

URL routes to service contract interface methods

Question

How do you authenticate API requests?

Click to reveal answer

Answer

Use Bearer token in Authorization header

Question

What is the API documentation URL?

Click to reveal answer

Answer

http://magento/rest/V1/schema (Swagger)

Question

What does ACL control?

Click to reveal answer

Answer

Authorization - who can access which API endpoints

Question

How do you test a REST endpoint?

Click to reveal answer

Answer

Use curl with Authorization header and JSON body

Revision Notes

Key Takeaways

  • 1. webapi.xml defines REST/SOAP routes mapped to service interfaces
  • 2. ACL resources control API authorization
  • 3. Service contracts (interfaces) define the API
  • 4. Authenticate with Bearer tokens from /V1/integration/admin/token
  • 5. Swagger docs at /rest/V1/schema

Interview Tips

  • • Explain the complete API request flow
  • • Know how to create and test REST endpoints
  • • Be ready to configure ACL for API access
  • • Discuss authentication and error handling

Cheat Sheet

webapi.xml:
  <route method="GET" url="/V1/warranty/:id">
    <service class="Interface" method="get"/>
    <resources><resource ref="acl::resource"/></resources>
  </route>

Auth: POST /V1/integration/admin/token
Test: curl -H "Authorization: Bearer TOKEN"
Docs: /rest/V1/schema