Skip to content

When should an interface go into the Model directory and when should it go in the Api directory?

Ievgen Shakhsuvarov edited this page Jul 16, 2019 · 3 revisions

In Magento we want to decouple modules by layers of N-tier architecture to provide better possibilities of replaceability or switch-ability of some parts of the system (i.e., substitute out of the box implementation with custom one, change UI, disable UI at all if we want to deploy headless integration and so on ) currently, we see the next 4 parts:

- API 
- Implementation of Business Logic for these API 
- Admin Ui
- Frontend UI

Here you can read more about Modularity Desirable State in Magento 2.

The main requirement we must to follow, applying this design concept is that All the modules should depend on the API module, while implementations could be easily swapped via di.xml

in most of Magento modules where Service Layer is already established (Customer, Catalog etc) you will notice that all the services and interfaces under the Api namespace are the services which supposed to be accessible via Web API (SOAP, REST) and we applied the same logic when started to decompose MSI modules as well. But along with Interfaces and Services which supposed to be accessible via Web API there are still extension points which don’t. For example, in MSI we applied new Validation approach having ValidationChain extension point filled with different validation checks, each of which should be a subtype of validation interface \Magento\InventoryApi\Model\SourceItemValidatorInterface. Even external modules could add particular validation to the chain. For example, Default Stock - Default Source validations are implemented by InventoryCatalog module, but not Inventory. But along with that SourceItemValidatorInterface is not going to be reachable via Web API, so clients of the system which just USE the system interfaces - no need to know about some validation which happens under the hood, just modules which need to add own validation logic should know about this interface. So that we decided to segregate these kind of interfaces and put:

  1. all the services and DTOs accessible via Web API under the Api namespace
  2. all the extension points which are not accessible via Web API under the Model namespace.

Sometimes you would even find class in API module under the Model namespace , for example,
\Magento\InventoryApi\Model\StockValidatorChain we did this because this class is an extension point via DI for other modules , like this

<type name="Magento\InventoryApi\Model\StockValidatorChain">
        <arguments>
            <argument name="validators" xsi:type="array">
                <item name="name" xsi:type="object">Magento\Inventory\Model\Stock\Validator\NameValidator</item>
            </argument>
        </arguments>
    </type>

if we left StockValidatorChain in the Magento\Inventory that would mean, that 3rd party developer who would like to fully substitute Inventory implementation still have to keep original Inventory module in the codebase but now, having all the Web APIs and extension points located under the roof on InventoryApi - non of the other modules need to depend on implementation Magento\Inventory, so that it could be easily substituted by another one and totally eliminated from the specific deployment

MSI Documentation:

  1. Technical Vision. Catalog Inventory
  2. Installation Guide
  3. List of Inventory APIs and their legacy analogs
  4. MSI Roadmap
  5. Known Issues in Order Lifecycle
  6. MSI User Guide
  7. DevDocs Documentation
  8. User Stories
  9. User Scenarios:
  10. Technical Designs:
  11. Admin UI
  12. MFTF Extension Tests
  13. Weekly MSI Demos
  14. Tutorials
Clone this wiki locally