Public interfaces and APIs

Learn about interaces and APIs.

What is an interface?#

A public interface is a set of code that third-party developers can call, implement, or build as a plug-in. Adobe guarantees that this code will not change in subsequent releases without a major version change.

Public interfaces for a module are marked with the @api annotation.

Example of public interface annotation#

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

namespace Magento\CatalogRule\Api;

/**
 * Interface CatalogRuleRepositoryInterface
 * @api
 * @since 100.1.0
 */
interface CatalogRuleRepositoryInterface
{
...
CopyCopied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace Magento\CatalogRule\Api;
8
9/**
10 * Interface CatalogRuleRepositoryInterface
11 * @api
12 * @since 100.1.0
13 */
14interface CatalogRuleRepositoryInterface
15{
16...

What is an API?#

An application programming interface (API) is a set of interfaces and their implementations that a module provides to other modules.

Example of an API interface implementation#

The Magento_CatalogRule module.

The Magento\CatalogRule\Api\CatalogRuleRepositoryInterface interface

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

namespace Magento\CatalogRule\Api;

use Magento\CatalogRule\Api\Data\RuleInterface;
use Magento\Framework\Exception\CouldNotDeleteException;
use Magento\Framework\Exception\CouldNotSaveException;
use Magento\Framework\Exception\NoSuchEntityException;

/**
 * Interface CatalogRuleRepositoryInterface
 * @api
 * @since 100.1.0
 */
interface CatalogRuleRepositoryInterface
{
    /**
     * @param RuleInterface $rule
     * @return RuleInterface
     * @throws CouldNotSaveException
     * @since 100.1.0
     */
    public function save(RuleInterface $rule): RuleInterface;

    /**
     * @param int $ruleId
     * @return RuleInterface
     * @throws NoSuchEntityException
     * @since 100.1.0
     */
    public function get(int $ruleId): RuleInterface;

    /**
     * @param RuleInterface $rule
     * @return bool
     * @throws CouldNotDeleteException
     * @since 100.1.0
     */
    public function delete(RuleInterface $rule): bool;

    /**
     * @param int $ruleId
     * @return bool
     * @throws CouldNotDeleteException
     * @since 100.1.0
     */
    public function deleteById(int $ruleId): bool;
}
CopyCopied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace Magento\CatalogRule\Api;
8
9use Magento\CatalogRule\Api\Data\RuleInterface;
10use Magento\Framework\Exception\CouldNotDeleteException;
11use Magento\Framework\Exception\CouldNotSaveException;
12use Magento\Framework\Exception\NoSuchEntityException;
13
14/**
15 * Interface CatalogRuleRepositoryInterface
16 * @api
17 * @since 100.1.0
18 */
19interface CatalogRuleRepositoryInterface
20{
21    /**
22     * @param RuleInterface $rule
23     * @return RuleInterface
24     * @throws CouldNotSaveException
25     * @since 100.1.0
26     */
27    public function save(RuleInterface $rule): RuleInterface;
28
29    /**
30     * @param int $ruleId
31     * @return RuleInterface
32     * @throws NoSuchEntityException
33     * @since 100.1.0
34     */
35    public function get(int $ruleId): RuleInterface;
36
37    /**
38     * @param RuleInterface $rule
39     * @return bool
40     * @throws CouldNotDeleteException
41     * @since 100.1.0
42     */
43    public function delete(RuleInterface $rule): bool;
44
45    /**
46     * @param int $ruleId
47     * @return bool
48     * @throws CouldNotDeleteException
49     * @since 100.1.0
50     */
51    public function deleteById(int $ruleId): bool;
52}

An interface implementation is declared in the di.xml as <preference />

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
...
    <preference for="Magento\CatalogRule\Api\CatalogRuleRepositoryInterface" type="Magento\CatalogRule\Model\CatalogRuleRepository"/>
...
</config>
CopyCopied to your clipboard
1<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
2...
3    <preference for="Magento\CatalogRule\Api\CatalogRuleRepositoryInterface" type="Magento\CatalogRule\Model\CatalogRuleRepository"/>
4...
5</config>

The Magento\CatalogRule\Model\CatalogRuleRepository implements the default methods of theCatalogRuleRepositoryInterface: save, get, delete, deleteById.

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

namespace Magento\CatalogRule\Model;

use Magento\CatalogRule\Api\Data;
use Magento\Framework\Exception\CouldNotDeleteException;
use Magento\Framework\Exception\CouldNotSaveException;
use Magento\Framework\Exception\NoSuchEntityException;
use Magento\Framework\Exception\ValidatorException;
use Magento\CatalogRule\Api\CatalogRuleRepositoryInterface;

class CatalogRuleRepository implements CatalogRuleRepositoryInterface
{
    ...

    /**
     * @inheritdoc
     */
    public function save(Data\RuleInterface $rule): Data\RuleInterface
    {
        ...
    }

    /**
     * @inheritdoc
     */
    public function get(int $ruleId): Data\RuleInterface
    {
        ...
    }

    /**
     * @inheritdoc
     */
    public function delete(Data\RuleInterface $rule): bool
    {
        ...
    }

    /**
     * @inheritdoc
     */
    public function deleteById(int $ruleId): bool
    {
        ...
    }
}
CopyCopied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace Magento\CatalogRule\Model;
8
9use Magento\CatalogRule\Api\Data;
10use Magento\Framework\Exception\CouldNotDeleteException;
11use Magento\Framework\Exception\CouldNotSaveException;
12use Magento\Framework\Exception\NoSuchEntityException;
13use Magento\Framework\Exception\ValidatorException;
14use Magento\CatalogRule\Api\CatalogRuleRepositoryInterface;
15
16class CatalogRuleRepository implements CatalogRuleRepositoryInterface
17{
18    ...
19
20    /**
21     * @inheritdoc
22     */
23    public function save(Data\RuleInterface $rule): Data\RuleInterface
24    {
25        ...
26    }
27
28    /**
29     * @inheritdoc
30     */
31    public function get(int $ruleId): Data\RuleInterface
32    {
33        ...
34    }
35
36    /**
37     * @inheritdoc
38     */
39    public function delete(Data\RuleInterface $rule): bool
40    {
41        ...
42    }
43
44    /**
45     * @inheritdoc
46     */
47    public function deleteById(int $ruleId): bool
48    {
49        ...
50    }
51}

API types#

The following items are considered types of APIs:

• Directory structure
• Configuration files structure
• Events
• Client API
• Provider API (SPI)

Directory structure and configuration file structure are types of APIs because extension developers use them. Developers write configurations, and place their static files in specified folders; so if the configuration file structure or directory structure changes in subsequent releases, modules and extensions may break.