Framework API¶

Service contracts exist to improve upgrades, decouple modules and formalise customisations
They exist in the form of interfaces implemented by classes
They allow an interface to stay the same while changing the implementation
Developers should rely only on classes' public methods

API Types¶

Data APIs
- Provice access to modules' entity data through CRUD methods
- Found in the module's Api/Data folder
Operational APIs
- Provides both entity data and allows for actions and operations
- Found in the module's Api folder
Repositories are the API equivalent to collections
Business Logic API provides actual business operations
The Framework API provides the interfaces and class implementations
(Model)Repository implements \Magento\Catalog\Api\ProductRespositoryInterface
Respository interfaces may extend Framework\Api\SearchCriteria and implement ::getList($criteria)

AbstractSimpleObject¶

Similar to Magento 1's Varien_Object
Has a data property, but no public magic getters or setters
Provides
- An array $data constructor parameter and $data property
- _get($key)
- setData($key, $value)
- __toArray()

SimpleBuilderInterface¶

Defines two methods
- create()
- getData()
AbstractSimpleObjectBuilder implements this by instantiating the object with the $data

AbstractServiceCollection¶

Service Collections are collections that get items from respositories rather than the ORM
Allows for converting filters and sorts into a SearchCriteria instance
Admin Grids often use Service Collections as a data source
Provides:
- __construct(EntityFactoryInterface, FilterBuilder, SearchCriteriaBuilder, SortOrderBuilder)
- addFieldToFilter($field, $condition)
- getSearchCriteria()
- createFilterData($field, $condition)

Repositories¶

Extend Magento\Framework\SearchCriteria
Exist to provide access to data sources
Allows the sourcing to be decoupled from data sources
Are services, so can be relied upon to be stable, where collections can not
Deal with data objects rather than models
Use SearchCriteria for filtering
Have a getList() method, expecting Magento\Framework\SearchCriteriaInterface

Magento\Customer\Api\CustomerRepositoryInterface example¶

Provides
- save(\Magento\Customer\Api\Data\CustomerInterface $customer, $passwordHash)
- get($email, $websiteId)
- getById($customerId)
- getList(\Magento\Framework\Api\SearchCriteriaInterface $searchCriteria)
- delete(\Magento\Customer\Api\Data\CustomerInterface $customer)
- deleteById($customerId)

SearchCriteria¶

Filters are added using $this->searchCriteriaBuilder->addFilters() calls followed by a create() call
SearchCriteriaInterface defines:
- getFilterGroups()
- setFilterGroups(array $filterGroups = null)
- getSortOrders()
- setSortOrders(array $sortOrders = null)
- getPageSize()
- setPageSize($pageSize)
- getCurrentPage()
- setCurrentPage($currentPage)

Architecture¶

SearchCriteriaBuilder
- Extends AbstractSimpleObjectBuilder
- create() creates
  - SearchCriteria
    - Extends AbstractSimpleObject
    - Implements SearchCriteriaInterface
    - Uses Search\FilterGroup
      - Uses Filter

Filter object¶

Extends AbstractSimpleObject
Adds methods to get/set the $data field
- get/setField()
- get/setValue()
- get/setConditionType()

Builder Relationships¶

Filters
- FilterGroup extends AbstractSimpleObject
- FilterGroupBuilder extends AbstractSimpleObjectBuilder
- Filters are set using FilterGroupBuilder::setFilters()
- FilterGroupBuilder::create() instantiates the FilterGroups
SortOrders
- SortOrder extends AbstractSimpleObject
- SortOrderBuilder extends AbstractSimpleObjectBuilder
- SortOrderBuilder creates the SortOrders based on setField() and setDirection()

SearchResultsInterface¶

Is the base interface returned by repositories' getList() methods
Provides
- getItems()
- setItems()
- getSearchCritera()
- setSearchCriteria(\Magento\Framework\Api\SearchCriteriaInterface $searchCriteria)
- getTotalCount()
- setTotalCount($totalCount)
Extends AbstractSimpleObject

Business Logic API¶

Is responsible for all logic not contained in Repositories or the Data API
Is responsible for basically all the actions a module can take
Example is Magento\Customer\Api\AccountManagementInterface
- Provides validate(), authenticate(), resendConfirmation()
- Implemented by Magento\Customer\Model\AccountManagement

Data API¶

Simplifies the SOAP API
Defines an internal API for accessing the Data Models
- Defines the getters and setters for fields
Should implement the API interface rather than plain data models
Can be implemented using one of two methods
- Create specific data objects that only contain data, with getters/setters. This is the preferred approach.
- Use normal models that implement Data API interfaces, but also contain business logic

Extensible Objects and Extension Attributes¶

Extensible Objects¶

Should extend Magento\Framework\Api\AbstractExtensibleObject
- Implements Magento\Framework\Api\CustomAttributesDataInterface
  - Defines
    - const CUSTOM_ATTRIBUTES
    - getCustomAttribute($attributeCode)
    - setCustomAttribute($attributeCode, $attributeValue)
    - getCustomAttributes()
    - setCustomAttributes(array $attributes)
  - Extends Magento\Framework\Api\ExtensibleDataInterface
    - Defines
      - const EXTENSION_ATTRIBUTES_KEY
Can call get- and setExtensionAttributes()
Api Data model interface defines attributes as constants
Data model implements the getters and setters
AbstractExtensibleObject accepts a constructor argument of ExtensionAttributesFactory or AttributeValueFactory, added in DI
Customer Example
- Customer\Api\Data\CustomerInterface defines attributes as constants, and defines the getters and setters
- Customer\Model\Data\Customer provides the getters and setters

Configuration¶

extension_attributes.xml:

/config/extension_attributes/
                             @for -- Path\To\Api\Data\Interface
                             attribute/
                                       @code
                                       @type
                                       resources/
                                                 @ref

Metadata Objects¶

Metadata objects are used to obtain a list of attributes
DefaultMetadataService implements MetadataServiceInterface
- Implements the public function getCustomAttributes($dataObjectClassName = null)
AttributeMetadata implements MetadataServiceInterface
MetadataObjectInterface defines get/setAttributeCode()

Customer Module Example¶

Magento\Customer\Model\Data\AttributeMetadata implements AttributeMetadataInterface
The Interface provides constants fpr the attribute metata keys such as attribute_code, frontend_input etc
The concretion extends AbstractSimpleObject and implements the getters for the Interface's constants

Web API¶

Exposes the module's Service Contract API through the Web API
Extends the Magento 1 API
Respositories and APIs can be made accessible through Web APIs
REST APIs define methods in webapi.xml
Has Areas for webapi_rest and webapi_soap, with their own di.xml files
API Calls are processed:
1. A URL is called
2. webapi.xml maps verbs and URLs to Service Class Interfaces and Methods
3. webapi.xml also defines the ACL groups
4. webapi_rest|soap/di.xml defines concretions for the Interfaces
5. The class/method is called

Configuration¶

webapi.xml:

/routes/
        route/
              @url
              @method -- GET or POST
              service/
                      @class -- \Path\To\Api\RepositoryInterface
                      @method -- class method to call
                      resources/
                                resource/
                                         @ref -- for ACL

Authentication¶

ACLs exist as self, anonynmous and a Magento ACL resource
Can be authenticated using OAuth for SOAP, tokens for REST or Sessions

SOAP¶

Tokens are created in the Admin at System > Integration
SOAP Wsdls are automatically generated based on Service Interfaces
- Accessible at /soap?wdsl&services=ModuleInterfaceV1,Module2InterfaceV1
- CustomerRespoitoryInterface::getList() would be specified as customerCustomerRepositoryV1getList

REST¶

Token requests look like /index.php/rest/V1/integration/admin/token, submitting username and password
API calls index.php/rest/V1/resource/id with a header Authorization:Bearer(_TOKEN_)