Edit in GitHubLog an issue

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#

Copied 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

Copied 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 />

Copied 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.

Copied 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.

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.