Service Contracts

Service contracts define stable API interfaces for module interactions.

Why service contracts matter:

• Stable API across versions
• Decoupled implementation
• Easy to test
• REST/GraphQL API generation
• Third-party integration

Service contract layers:

API Layer (Interfaces)
├── Data Interfaces (PostInterface)
├── Repository Interfaces (PostRepositoryInterface)
└── Service Interfaces (PostServiceInterface)

Implementation Layer
├── Models (Post)
├── Resource Models (Post)
├── Repositories (PostRepository)
└── Service Classes (PostService)

Module structure:

app/code/Vendor/Blog/
├── Api/
│   ├── Data/
│   │   ├── PostInterface.php
│   │   └── PostExtensionInterface.php
│   ├── PostRepositoryInterface.php
│   └── PostServiceInterface.php
├── Model/
│   ├── Post.php
│   ├── PostRepository.php
│   └── ResourceModel/
│       ├── Post.php
│       └── Post/Collection.php
└── etc/
    ├── module.xml
    ├── di.xml
    └── webapi.xml

Data interfaces define the structure of data objects.

Data interface:

<?php
namespace Vendor\Blog\Api\Data;

interface PostInterface
{
    const TITLE = 'title';
    const CONTENT = 'content';
    const STATUS = 'status';
    const CREATED_AT = 'created_at';
    const UPDATED_AT = 'updated_at';
    
    public function getId(): ?int;
    public function getTitle(): string;
    public function setTitle(string $title): self;
    public function getContent(): string;
    public function setContent(string $content): self;
    public function getStatus(): int;
    public function setStatus(int $status): self;
    public function getCreatedAt(): ?string;
    public function setCreatedAt(string $createdAt): self;
    public function getUpdatedAt(): ?string;
    public function setUpdatedAt(string $updatedAt): self;
}

Data interface best practices:

// 1. Use constants for field names
const TITLE = 'title';

// 2. Return self for fluent interface
public function setTitle(string $title): self;

// 3. Use nullable for optional fields
public function getCreatedAt(): ?string;

// 4. Type-hint all parameters
public function setStatus(int $status): self;

// 5. Document with PHPDoc
/**
 * Get post title
 * @return string
 */
public function getTitle(): string;

Repository interfaces define CRUD operations for entities.

Repository interface:

<?php
namespace Vendor\Blog\Api;

use Magento\Framework\Api\SearchCriteriaInterface;
use Magento\Framework\Api\SearchResultsInterface;
use Vendor\Blog\Api\Data\PostInterface;

interface PostRepositoryInterface
{
    /**
     * Get post by ID
     * @param int $id
     * @return PostInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function get($id): PostInterface;
    
    /**
     * Get list of posts
     * @param SearchCriteriaInterface $searchCriteria
     * @return SearchResultsInterface
     */
    public function getList(SearchCriteriaInterface $searchCriteria): SearchResultsInterface;
    
    /**
     * Save post
     * @param PostInterface $post
     * @return PostInterface
     */
    public function save(PostInterface $post): PostInterface;
    
    /**
     * Delete post
     * @param PostInterface $post
     * @return bool
     */
    public function delete(PostInterface $post): bool;
    
    /**
     * Delete post by ID
     * @param int $id
     * @return bool
     */
    public function deleteById($id): bool;
}

Service interface:

<?php
namespace Vendor\Blog\Api;

interface PostServiceInterface
{
    public function publish(int $id): PostInterface;
    public function archive(int $id): PostInterface;
    public function duplicate(int $id): PostInterface;
}

Benefits and practical applications of service contracts.

1. API generation:

<!-- webapi.xml automatically uses service contracts -->
<route url="/V1/posts/:id" method="GET">
    <service class="Vendor\Blog\Api\PostRepositoryInterface" method="get"/>
</route>

2. Testing:

// Mock the interface, not the implementation
$mockPost = $this->createMock(PostInterface::class);
$mockRepo = $this->createMock(PostRepositoryInterface::class);
$mockRepo->method('get')->willReturn($mockPost);

// Test against interface
$this->assertEquals($mockPost, $mockRepo->get(1));

3. Version compatibility:

// Interface remains stable across versions
// Implementation can change without breaking API

// Version 1.0
interface PostRepositoryInterface {
    get($id);
    save(PostInterface $post);
}

// Version 2.0 - same interface, new implementation
// Still works with old code

4. Third-party integration:

// Third-party modules can use your interfaces
public function processPost(
    \Vendor\Blog\Api\PostRepositoryInterface $postRepo,
    int $postId
) {
    $post = $postRepo->get($postId);
    // Process...
}

5. REST/GraphQL API:

# Service contracts automatically expose REST API
GET /rest/V1/posts/1
POST /rest/V1/posts
PUT /rest/V1/posts/1
DELETE /rest/V1/posts/1

Implementation binding:

<!-- di.xml -->
<preference for="Vendor\Blog\Api\PostRepositoryInterface"
            type="Vendor\Blog\Model\PostRepository"/>