Service Contracts after 8 years – antipatterns, SearchCriteria without limit, testing

Service Contracts were introduced in Magento 2.0 as the stable API layer between modules. Eight years later I can look at what worked, what became antipatterns, and what the platform itself got wrong. SearchCriteria without a limit, anemic repositories, and over-reliance on Service Contracts where Events would have been cleaner – I show the patterns and the fixes.

What Service Contracts got right

<?php

// The original promise: if you code to interfaces, module upgrades don't break you
// In 2026 this largely delivered:

// Good: coding to ProductRepositoryInterface means you can mock it in tests
class ProductService
{
    public function __construct(
        private \Magento\Catalog\Api\ProductRepositoryInterface $productRepository
    ) {}
    // Mockable, testable, replaceable via preference
}

// Good: REST API is automatically generated from @api-annotated interfaces
// A Magento module with proper Service Contracts gets REST endpoints for free

// Good: DTO interfaces (ProductInterface, OrderInterface) give a stable data contract
// even if the underlying Model class changes

Antipattern 1: SearchCriteria without limit

<?php

// THIS IS A BUG - and one I see constantly in real codebases
class OrderExporter
{
    public function getAllOrders(): array
    {
        // No page size limit - will try to load EVERY order into memory
        $sc = $this->searchCriteriaBuilder
            ->addFilter('status', 'complete')
            ->create(); // Missing: ->setPageSize(1000)

        return $this->orderRepository->getList($sc)->getItems();
        // On a shop with 500,000 orders: OutOfMemoryError, timeout, or killed process
    }
}

// CORRECT: always set a page size, batch-process
class OrderExporter
{
    private const BATCH_SIZE = 500;

    public function exportAll(): \Generator
    {
        $page = 1;
        do {
            $sc = $this->searchCriteriaBuilder
                ->addFilter('status', 'complete')
                ->setPageSize(self::BATCH_SIZE)
                ->setCurrentPage($page)
                ->create();

            $result = $this->orderRepository->getList($sc);
            $items  = $result->getItems();

            foreach ($items as $order) {
                yield $order;
            }

            $page++;
        } while (count($items) === self::BATCH_SIZE);
    }
}

Antipattern 2: Anemic repository

<?php

// Repository as a thin wrapper with no domain knowledge - common but wrong
class OrderRepository implements OrderRepositoryInterface
{
    public function getById(int $id): OrderInterface { /* ... */ }
    public function getList(SearchCriteriaInterface $sc): SearchResultsInterface { /* ... */ }
    public function save(OrderInterface $order): OrderInterface { /* ... */ }
    public function delete(OrderInterface $order): bool { /* ... */ }
    public function deleteById(int $id): bool { /* ... */ }
    // Nothing domain-specific - just CRUD
}

// Callers then implement domain logic themselves:
class OrderService
{
    public function getCompletedOrdersForLastMonth(): array
    {
        $from = new \DateTime('-1 month');
        return $this->orderRepository->getList(
            $this->searchCriteriaBuilder
                ->addFilter('status', 'complete')
                ->addFilter('created_at', $from->format('Y-m-d'), 'gt')
                ->setPageSize(1000)
                ->create()
        )->getItems();
    }
}

// BETTER: Add domain methods to the repository interface
interface OrderRepositoryInterface
{
    // Standard CRUD...
    public function getById(int $id): OrderInterface;
    public function getList(SearchCriteriaInterface $sc): SearchResultsInterface;
    public function save(OrderInterface $order): OrderInterface;

    // Domain-specific methods that belong here
    /** @return OrderInterface[] */
    public function getCompletedSince(\DateTimeInterface $since, int $limit = 500): array;

    /** @return OrderInterface[] */
    public function getPendingForCustomer(int $customerId): array;

    public function countByStatus(string $status): int;
}

Antipattern 3: Events vs Service Contracts confusion

<?php

// When to use Service Contract vs Event Observer?
// Rule: if CALLER needs to influence the result, use Service Contract (plugin)
// Rule: if CALLER just needs to REACT, use Event Observer

// WRONG: Using a plugin to simply react to something
class OrderPlacedPlugin
{
    public function afterPlace(
        \Magento\Sales\Api\OrderManagementInterface $subject,
        \Magento\Sales\Api\Data\OrderInterface $result
    ) {
        // Just sending an email - no need to intercept, just react
        $this->emailService->sendConfirmation($result);
        return $result;
    }
}

// RIGHT: Use an observer for side effects
// etc/events.xml:
// <event name="sales_order_place_after">
//     <observer name="send_confirmation" instance="Vendor\Module\Observer\SendOrderConfirmation"/>
// </event>

// Plugin is appropriate when you need to modify behaviour:
class PriceValidationPlugin
{
    public function beforePlace(
        \Magento\Sales\Api\OrderManagementInterface $subject,
        \Magento\Sales\Api\Data\OrderInterface $order
    ): array {
        if (!$this->isPriceValid($order)) {
            throw new \Magento\Framework\Exception\LocalizedException(__('Price changed'));
        }
        return [$order]; // plugins modify input/output
    }
}

Testing Service Contracts – the right way

<?php

use PHPUnit\Framework\TestCase;

class OrderServiceTest extends TestCase
{
    // Mock the interface, not the concrete class
    private \Magento\Sales\Api\OrderRepositoryInterface $orderRepository;

    protected function setUp(): void
    {
        $this->orderRepository = $this->createMock(
            \Magento\Sales\Api\OrderRepositoryInterface::class
        );
    }

    public function testGetCompletedOrdersReturnsBatchedResults(): void
    {
        $order1 = $this->createMock(\Magento\Sales\Api\Data\OrderInterface::class);
        $order2 = $this->createMock(\Magento\Sales\Api\Data\OrderInterface::class);

        $searchResult = $this->createMock(\Magento\Framework\Api\SearchResultsInterface::class);
        $searchResult->method('getItems')->willReturn([$order1, $order2]);
        $searchResult->method('getTotalCount')->willReturn(2);

        $this->orderRepository
            ->method('getList')
            ->willReturn($searchResult);

        $service = new OrderService($this->orderRepository, $this->searchCriteriaBuilder);
        $result  = iterator_to_array($service->exportAll());

        $this->assertCount(2, $result);
    }
}

Summary

Service Contracts are one of Magento 2’s best architectural decisions – they made modules loosely coupled and testable. Eight years of usage reveal the main antipatterns: missing page size limits on getList (the most dangerous), repositories that are too anemic, and using plugins where observers would be cleaner. The fixes are always straightforward once you recognise the pattern. Code to the interface, always set a page size, and let domain knowledge live in the repository rather than the service layer.