Magento 2 Custom REST Endpoints: Building Your Own API

When Magento’s API coverage does not reach your use case - a custom entity, a composite operation, a partner-specific format - you build your own endpoint. The framework makes this clean: an XML route, a PHP interface, an implementation. The discipline is in the details: ACL scoping, anonymous access control, and interfaces designed for the long term.

The Three Pieces

1. The route (etc/webapi.xml):

<route url="/V1/acme-locations/:id" method="GET">
    <service class="Acme\Locations\Api\LocationRepositoryInterface" method="getById"/>
    <resources>
        <resource ref="Acme_Locations::location_view"/>
    </resources>
</route>

2. The service contract (Api/LocationRepositoryInterface.php): a PHP interface with strict docblock typing - the docblocks are the API schema for routing and serialisation:

/**
 * @param int $id
 * @return \Acme\Locations\Api\Data\LocationInterface
 * @throws \Magento\Framework\Exception\NoSuchEntityException
 */
public function getById(int $id): \Acme\Locations\Api\Data\LocationInterface;

3. The implementation: a class implementing the interface, wired via di.xml preference. It does the work and returns data objects implementing your Api\Data interfaces.

ACL Resources: Who May Call

The <resource ref> line is your security boundary:

• Acme_Locations::location_view - requires an authenticated token whose integration has this ACL. Define new resources in etc/acl.xml under the Magento_Backend tree so admins can grant them via the integration UI
• Magento_Customer::customer - customer token required
• anonymous - public internet. Use only for genuinely public data, and say out loud, in code review, why the data is public

The most common custom-API security failure is anonymous on an endpoint that leaks order or customer data. Treat every anonymous resource as a security review item.

Designing the Contract

• Return data interfaces, not models: your LocationInterface with getters is the stable contract; the model behind it can change freely
• Throw framework exceptions: NoSuchEntityException becomes a 404, LocalizedException a 400, AuthorizationException a 403 - correct HTTP semantics for free
• Search endpoints: accept SearchCriteriaInterface for list endpoints; the filter/sort/page machinery comes built in
• Version in the URL (/V1/): when the contract must break, /V2/ lets old consumers live

Testing

• Integration tests hitting webapi.xml routes via the test framework’s API client catch routing and serialisation errors unit tests miss
• Manual verification in Postman against each auth type: integration token, customer token, anonymous - confirm 403s where you expect 403s

A well-built custom endpoint is indistinguishable from core API: same conventions, same exceptions, same ACL model. Consumers of your API should never need to know it was not shipped by Adobe - that is the quality bar, and it is very achievable.