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.
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 Adobe Commerce and Magento Open Source releases. For more information, see Backward compatibility.
Example of public interface annotation#
Copied to your clipboard1<?php2/**3 * Copyright © Magento, Inc. All rights reserved.4 * See COPYING.txt for license details.5 */67namespace Magento\CatalogRule\Api;89/**10 * Interface CatalogRuleRepositoryInterface11 * @api12 * @since 100.1.013 */14interface CatalogRuleRepositoryInterface15{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
Copied to your clipboard1<?php2/**3 * Copyright © Magento, Inc. All rights reserved.4 * See COPYING.txt for license details.5 */67namespace Magento\CatalogRule\Api;89use Magento\CatalogRule\Api\Data\RuleInterface;10use Magento\Framework\Exception\CouldNotDeleteException;11use Magento\Framework\Exception\CouldNotSaveException;12use Magento\Framework\Exception\NoSuchEntityException;1314/**15 * Interface CatalogRuleRepositoryInterface16 * @api17 * @since 100.1.018 */19interface CatalogRuleRepositoryInterface20{21 /**22 * @param RuleInterface $rule23 * @return RuleInterface24 * @throws CouldNotSaveException25 * @since 100.1.026 */27 public function save(RuleInterface $rule): RuleInterface;2829 /**30 * @param int $ruleId31 * @return RuleInterface32 * @throws NoSuchEntityException33 * @since 100.1.034 */35 public function get(int $ruleId): RuleInterface;3637 /**38 * @param RuleInterface $rule39 * @return bool40 * @throws CouldNotDeleteException41 * @since 100.1.042 */43 public function delete(RuleInterface $rule): bool;4445 /**46 * @param int $ruleId47 * @return bool48 * @throws CouldNotDeleteException49 * @since 100.1.050 */51 public function deleteById(int $ruleId): bool;52}
An interface implementation is declared in the di.xml
as <preference />
Copied to your clipboard1<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
.
Copied to your clipboard1<?php2/**3 * Copyright © Magento, Inc. All rights reserved.4 * See COPYING.txt for license details.5 */67namespace Magento\CatalogRule\Model;89use 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;1516class CatalogRuleRepository implements CatalogRuleRepositoryInterface17{18 ...1920 /**21 * @inheritdoc22 */23 public function save(Data\RuleInterface $rule): Data\RuleInterface24 {25 ...26 }2728 /**29 * @inheritdoc30 */31 public function get(int $ruleId): Data\RuleInterface32 {33 ...34 }3536 /**37 * @inheritdoc38 */39 public function delete(Data\RuleInterface $rule): bool40 {41 ...42 }4344 /**45 * @inheritdoc46 */47 public function deleteById(int $ruleId): bool48 {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.