Public interfaces & APIs
What is a public interface?
A public interface is a set of code that third-party developers can call, implement, or build as a plug-in. Magento guarantees that this code will not change in subsequent releases without a major version change.
Public interfaces for a module are marked with @api
annotation.
Third-party developers should use only these interfaces, that is, interfaces with the @api
annotation. You can use other interfaces but those may be modified or removed in subsequent Magento releases. For more information, see Backward compatibility.
Example of public interface annotation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?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
{
...
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<?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;
}
An interface implementation is declared in the di.xml
as <preference />
1
2
3
4
5
<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>
The Magento\CatalogRule\Model\CatalogRuleRepository
implements the default methods of theCatalogRuleRepositoryInterface
: save
, get
, delete
, deleteById
.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<?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
{
...
}
}
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.