Service contracts

A service contract is a set of PHP interfaces that is defined by a module. This contract comprises data interfaces and service interfaces.

The role of the data interface is to preserve data integrity, while the role of the service interface is to hide the business logic details from service consumers.

Data interfaces define various functions, such as validation, entity information, search related functions, and so on. They are defined within the Api/Data directory of an individual module. To better understand the actual meaning of it, let's take a look at the data interfaces for the Magento_Cms module. In the vendor/magento/module-cms/Api/Data/ directory, there are four interfaces defined, as follows:

BlockInterface.php
BlockSearchResultsInterface.php
PageInterface.php
PageSearchResultsInterface.php

The CMS module actually deals with two entities, one being Block and the other one being Page. Looking at the interfaces defined in the preceding code, we can see that we have separate data interface for the entity itself and separate data interface for search results.

Let's take a closer look at the (stripped) contents of the BlockInterface.php file, which is defined as follows:

namespace Magento\Cms\Api\Data;

interface BlockInterface
{
    const BLOCK_ID      = 'block_id';
    const IDENTIFIER    = 'identifier';
    const TITLE         = 'title';
    const CONTENT       = 'content';
    const CREATION_TIME = 'creation_time';
    const UPDATE_TIME   = 'update_time';
    const IS_ACTIVE     = 'is_active';

    public function getId();
    public function getIdentifier();
    public function getTitle();
    public function getContent();
    public function getCreationTime();
    public function getUpdateTime();
    public function isActive();
    public function setId($id);
    public function setIdentifier($identifier);
    public function setTitle($title);
    public function setContent($content);
    public function setCreationTime($creationTime);
    public function setUpdateTime($updateTime);
    public function setIsActive($isActive);
}

The preceding interface defines all the getter and setter methods for the entity at hand along with the constant values that denote entity field names. These data interfaces do not include management actions, such as delete. The implementation of this specific interface can be seen in the vendor/magento/module-cms/Model/Block.php file, where these constants come to use, as follows (partially):

public function getTitle()
{
    return $this->getData(self::TITLE);
}

public function setTitle($title)
{
    return $this->setData(self::TITLE, $title);
}

Service interfaces are the ones that include management, repository, and metadata interfaces. These interfaces are defined directly within the module's Api directory. Looking back at the Magento Cms module, its vendor/magento/module-cms/Api/ directory has two service interfaces, which are defined as follows:

BlockRepositoryInterface.php
PageRepositoryInterface.php

A quick look into the contents of BlockRepositoryInterface.php reveals the following (partial) content:

namespace Magento\Cms\Api;

use Magento\Framework\Api\SearchCriteriaInterface;

interface BlockRepositoryInterface
{
    public function save(Data\BlockInterface $block);
    public function getById($blockId);
    public function getList(SearchCriteriaInterface $searchCriteria);
    public function delete(Data\BlockInterface $block);
    public function deleteById($blockId);
}

Here, we see methods that are used to save, fetch, search, and delete the entity.

These interfaces are then implemented via the Web API definitions, as we will see later in Chapter 9, The Web API. The result is well-defined and durable API's that other modules and third-party integrators can consume.