Magento 2 Service Contracts & Repositories
Before writing code
Fetch live docs:
- Fetch
https://developer.adobe.com/commerce/php/development/components/web-api/services/ for service contract guide
- Fetch
https://developer.adobe.com/commerce/php/development/components/searching-with-repositories/ for SearchCriteria patterns
- Web-search
site:developer.adobe.com commerce php development components service-contracts for additional reference
Conceptual Architecture
What Service Contracts Are
Service contracts are PHP interfaces that define a module's public API. They guarantee backward compatibility — implementations can change across versions without breaking consumers.
Three Interface Categories
Repository Interfaces (Api/SomeRepositoryInterface.php)
getById($id) — retrieve single entity
save(SomeInterface $entity) — create or update
delete(SomeInterface $entity) — remove
getList(SearchCriteriaInterface $criteria) — filtered/sorted/paginated results
Data Interfaces (Api/Data/SomeInterface.php)
- Define getters and setters for entity fields
getId(), setId($id), getName(), setName($name), etc.
- Constants for field names:
const NAME = 'name';
SearchResults Interface (Api/Data/SomeSearchResultsInterface.php)
- Extends
Magento\Framework\Api\SearchResultsInterface
- Wraps
getItems() / setItems() with typed returns
SearchCriteria Pattern
Used for querying repositories with filters, sorting, and pagination:
- SearchCriteriaBuilder — fluent builder for criteria
- FilterBuilder — builds individual filter conditions
- FilterGroupBuilder — groups filters with AND/OR logic
- SortOrderBuilder — defines sort order
- CollectionProcessorInterface — applies criteria to collections
Filter Logic
- Filters within a FilterGroup are OR'd together
- FilterGroups are AND'd together
- Condition types:
eq, neq, gt, gteq, lt, lteq, like, in, nin, notnull, null, from, to
Repository Implementation Pattern
The concrete repository class:
- Injects: Model Factory, Resource Model, Collection Factory, SearchResultsFactory, CollectionProcessor
getById() — creates model via factory, loads via resource model
save() — calls resource model save(), handles exceptions
delete() — calls resource model delete()
getList() — creates collection, applies criteria via CollectionProcessor, wraps in SearchResults
Service Contracts as Web API
When you define a service contract interface and map it in webapi.xml, the same code serves:
- REST API endpoints
- SOAP API endpoints
- Internal PHP calls
Best Practices
- Always define data interfaces — don't expose models directly
- Use typed return types and parameter types on all interface methods
- Add
@api annotation to indicate public API stability
- Use
SearchCriteriaBuilder instead of raw collection filtering in service layer
- Throw specific exceptions:
NoSuchEntityException, CouldNotSaveException, CouldNotDeleteException
- Map service contracts in
webapi.xml for automatic REST/SOAP exposure
Fetch the service contracts and searching-with-repositories docs for exact interface signatures, exception classes, and CollectionProcessor usage before implementing.
1---2name: magento-service-contracts3description: Implement Magento 2 service contracts — repository interfaces, data interfaces, SearchCriteria, and the repository pattern. Use when building module APIs, data access layers, or integrating with Magento's Web API.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/magento-service-contracts7---89# Magento 2 Service Contracts & Repositories1011## Before writing code1213**Fetch live docs**:141. Fetch `https://developer.adobe.com/commerce/php/development/components/web-api/services/` for service contract guide152. Fetch `https://developer.adobe.com/commerce/php/development/components/searching-with-repositories/` for SearchCriteria patterns163. Web-search `site:developer.adobe.com commerce php development components service-contracts` for additional reference1718## Conceptual Architecture1920### What Service Contracts Are2122Service contracts are **PHP interfaces** that define a module's public API. They guarantee backward compatibility — implementations can change across versions without breaking consumers.2324### Three Interface Categories25261. **Repository Interfaces** (`Api/SomeRepositoryInterface.php`)27 - `getById($id)` — retrieve single entity28 - `save(SomeInterface $entity)` — create or update29 - `delete(SomeInterface $entity)` — remove30 - `getList(SearchCriteriaInterface $criteria)` — filtered/sorted/paginated results31322. **Data Interfaces** (`Api/Data/SomeInterface.php`)33 - Define getters and setters for entity fields34 - `getId()`, `setId($id)`, `getName()`, `setName($name)`, etc.35 - Constants for field names: `const NAME = 'name';`36373. **SearchResults Interface** (`Api/Data/SomeSearchResultsInterface.php`)38 - Extends `Magento\Framework\Api\SearchResultsInterface`39 - Wraps `getItems()` / `setItems()` with typed returns4041### SearchCriteria Pattern4243Used for querying repositories with filters, sorting, and pagination:4445- **SearchCriteriaBuilder** — fluent builder for criteria46- **FilterBuilder** — builds individual filter conditions47- **FilterGroupBuilder** — groups filters with AND/OR logic48- **SortOrderBuilder** — defines sort order49- **CollectionProcessorInterface** — applies criteria to collections5051### Filter Logic5253- Filters within a **FilterGroup** are OR'd together54- **FilterGroups** are AND'd together55- Condition types: `eq`, `neq`, `gt`, `gteq`, `lt`, `lteq`, `like`, `in`, `nin`, `notnull`, `null`, `from`, `to`5657### Repository Implementation Pattern5859The concrete repository class:601. Injects: Model Factory, Resource Model, Collection Factory, SearchResultsFactory, CollectionProcessor612. `getById()` — creates model via factory, loads via resource model623. `save()` — calls resource model `save()`, handles exceptions634. `delete()` — calls resource model `delete()`645. `getList()` — creates collection, applies criteria via CollectionProcessor, wraps in SearchResults6566### Service Contracts as Web API6768When you define a service contract interface and map it in `webapi.xml`, the same code serves:69- REST API endpoints70- SOAP API endpoints71- Internal PHP calls7273### Best Practices7475- Always define data interfaces — don't expose models directly76- Use typed return types and parameter types on all interface methods77- Add `@api` annotation to indicate public API stability78- Use `SearchCriteriaBuilder` instead of raw collection filtering in service layer79- Throw specific exceptions: `NoSuchEntityException`, `CouldNotSaveException`, `CouldNotDeleteException`80- Map service contracts in `webapi.xml` for automatic REST/SOAP exposure8182Fetch the service contracts and searching-with-repositories docs for exact interface signatures, exception classes, and CollectionProcessor usage before implementing.