Igor Miniailo - Magento 2 API Design Best Practices

© 2017 Magento, Inc. Page | 1
API Design
Best practices
Igor Miniailo
Magento 2 Architect

Why is API so crucial?

Semantic Versioning
Version numbers are in the format
MAJOR.MINOR.PATCH, where:
– MAJOR indicates incompatible API changes
– MINOR indicates backward-compatible
functionality has been added
– PATCH indicates backward-compatible bug
fixes

The backward compatibility policy
applies to PHP code annotated with
@api

Public and Private code

Public vs Private code
Private code is not supposed to
be used by third party modules,
so, in most cases, its
modifications will only trigger
PATCH version bumps.
Changes in public code always
trigger MINOR or MAJOR
version bumps.

What examples of Public code Magento has?
• PHP Interface (marked with @api)
• PHP Class (marked with @api)
• Javascript Interface (marked with @api)
• Javascript Class (marked with @api)
• Virtual Type (marked with @api)
• URL paths
• Console commands and their arguments
• Less Variables & Mixins
• Message queue topics and their data types
• UI component declarations
• Layout handles declared by modules
• Events triggered by component (both static dynamic)
• Schema of configuration types introduced by module
• Structure of System Configuration fields used by module

API vs SPI (Extension Points)
A PHP Interface in Magento can be used several ways by the core
product and extension developers.
• As an API. is a set of interfaces and their
implementations that a module provides to other
modules
• As a Service Provider Interface (SPI). is a set of
interfaces that a module uses internally and allows their
implementation by other modules.
• As both. APIs and SPIs are not mutually exclusive.

After the code is released, both API and SPI can
be evolved in a backwards-compatible way. But
both have their specific limitations.

We do not distinguish them separately.
SPIs are annotated the same as APIs.

Who decides whether interface/class belong to API or SPI?
YOU

Dependency Rules API
If a module uses (calls) an API, it should be dependent on the MAJOR
version.
API dependency example
{
...
"require": {
"magento/module-customer": "~100.0", // (>=100.0 <101.0.0)
},
...
}

Dependency Rules SPI
If a module implements an API/SPI, it should be dependent on the
MAJOR+MINOR version.
SPI dependency example
{
...
"require": {
"magento/module-customer": "~100.0.0", // (>=100.0.0 <100.1.0)
},
...
}

http://devdocs.magento.com/guides/v2.1/release-notes/backward-
incompatible-changes-2.1.html

Prohibited Code Changes

• Interface/class removal
• Public & protected method removal
• Introduction of a method to a class or
interface
PHP - Prohibited Code Changes

MagentoCatalogApiCategoryRepositoryInterface

MagentoCatalogApiCategoryListInterface

• Static function removal
• Parameter addition in public methods
• Parameter addition in protected
methods

• Method argument type modification
• Modification of types of thrown
exceptions (unless a new exception is
a subtype of the old one)
• Constructor modification

class ExistingClass
{
/**
* @var NewDependencyInterface $newDependency
*/
private $newDependency;
public function __construct(
OldDependencyIntreface $oldDependency,
$oldRequiredConstructorParameter,
$oldOptinalConstructorParameter = null,
NewDependencyInterface $newDependency = null
) {
...
$this>newDependency = $newDependency ?: MagentoFrameworkAppObjectManager::getInstance()
->get(NewDependencyInterface::class);
...
}
public function existingFunction() {
// Existing functionality
...
// Use $this->newDependency wherever the new dependency is needed
...
}
}

• Modifying the default values of
optional arguments in public and
protected methods
• Removing or renaming constants

The main rule is that backwards compatibility
is more important than niceness and effort of
the implementation.

Coupling Between Objects Reaches Its Limit with
a New Dependency

We MUST do continuous Refactoring!
Backward Compatibility should not be an excuse
for not doing refactoring!

Backward Compatible Fix
*it works (most of the time), but code quality
is far from good enough

Good object oriented programming in the service layer is basically
functional programming:
• constructor injection
• immutable state
• single responsibility principle
• uniform interfaces
• value objects passed across services
Bringing these concepts to an extreme leads to single-method,
immutable objects.

Why execute but not __invoke?

PHP 7
• Return Types
• Scalar Type hinting

Repositories
In Magento 2 Repositories are considered as an implementation
of Facade pattern which provides a simplified interface to a larger body
of code responsible for Domain Entity management.
The main intention is to make API more readable and reduce
dependencies of business logic code on the inner workings of a
module, since most code uses the facade, thus allowing more flexibility
in developing the system.

Repositories

Good API design
Don't make your client do anything you can do
for them (this reduces the amount of boilerplate
code your client will have)

Headless Magento

RESTful API

Swagger
http://devdocs.magento.com/guides/v2.2/rest/generate-local.html

MSI Base Concept

LSD
* Load – Save – Delete

2 Business operations – 1 API
1. Stock Setting (Import, Synchronization with ERP)
2. Stock Deduction (Checkout)

Bad designed APIs could lead to Big issues

The reason of DB Wait Lock on Checkout

Reservation - the entity is used when the order is placed and
we need to reserve some product quantity in stock.
Reservations are append only operations and help us to prevent
blocking operations and race conditions at the time of checkout.
Reservation mechanism
https://github.com/magento-engcom/msi/wiki/Reservations

Order Placement – Step 1
France Warehouse
SKU-1: 5qty
EU Stock
SKU-1: 15qty
Italy Warehouse
SKU-1: 10qty
Raw data Index Reservations
No records
Available Qty: 15qty (data from index, empty reservations)

Action: Customer buys 5 products on frontend

France Warehouse
SKU-1: 5qty
EU Stock
SKU-1: 15qty
Italy Warehouse
SKU-1: 10qty
SKU-1: -5
Available Qty: 10qty (data from index 15, apply all reservations -5)
Data is NOT changed Reservation has been
added

Action: Admin makes a re-order 3 products out of 5 returned,
and new order consists of 2 products

France Warehouse
SKU-1: 5qty
EU Stock
SKU-1: 15qty
Italy Warehouse
SKU-1: 10qty
SKU-1: -5
SKU-1: +3
Available Qty: 13qty (data from index 15, apply reservations -5+3)
Data is NOT changed
Reservation has been added

Action: Admin completes order. Re-index was run.

France Warehouse
SKU-1: 3qty
EU Stock
SKU-1: 13qty
Italy Warehouse
SKU-1: 10qty
SKU-1: -5
SKU-1: +3
SKU-1: +2
Available Qty: 13qty (data from index 13, apply reservations -5+3+2=0)
Data is CHANGED Compensation Reservation
has been added

Action: Reservation cleaning
Looping through these reservations we could find reservations
which in sum gives 0 (Zero) and remove them.

(like Step 1)
France Warehouse
SKU-1: 3qty
EU Stock
SKU-1: 13qty
Italy Warehouse
SKU-1: 10qty
Available Qty: 13qty (data from index, empty reservations)
Data is NOT changed Reservations have been removed
No records

API interface to test

So, what’s about testing?

What about fixtures?

#MageConf, Kyiv 15-16 of December
http://mageconf.com/

Q & A
@iminyaylo
engcom@magent.com

Igor Miniailo - Magento 2 API Design Best Practices

More Related Content

What's hot (15)

Similar to Igor Miniailo - Magento 2 API Design Best Practices (20)

More from Atwix (20)

Recently uploaded (20)

Igor Miniailo - Magento 2 API Design Best Practices

Editor's Notes