diff --git a/_data/toc/coding-standards.yml b/_data/toc/coding-standards.yml index 718a32cb73d..a63115d50fb 100644 --- a/_data/toc/coding-standards.yml +++ b/_data/toc/coding-standards.yml @@ -35,6 +35,7 @@ pages: url: /coding-standards/technical-guidelines.html - label: Technical vision + url: /coding-standards/technical-vision/index.html children: - label: Web Api diff --git a/guides/v2.0/coding-standards/technical-vision/index.md b/guides/v2.0/coding-standards/technical-vision/index.md new file mode 100644 index 00000000000..15932c1287e --- /dev/null +++ b/guides/v2.0/coding-standards/technical-vision/index.md @@ -0,0 +1,8 @@ +--- +group: coding-standards +title: Magento technical vision +--- + +The Magento technical vision is a collection of documents that describe the desired state of the Magento platform. + +Each individual technical vision document relates to a set of modules that arelogically grouped together. Individual documents typically describe a component's place in the system, its architecture, extension scenarios. and a list of invariants that must be preserved at all times during component refactoring or extension to ensure consistency. diff --git a/guides/v2.1/coding-standards/technical-vision/index.md b/guides/v2.1/coding-standards/technical-vision/index.md new file mode 100644 index 00000000000..15932c1287e --- /dev/null +++ b/guides/v2.1/coding-standards/technical-vision/index.md @@ -0,0 +1,8 @@ +--- +group: coding-standards +title: Magento technical vision +--- + +The Magento technical vision is a collection of documents that describe the desired state of the Magento platform. + +Each individual technical vision document relates to a set of modules that arelogically grouped together. Individual documents typically describe a component's place in the system, its architecture, extension scenarios. and a list of invariants that must be preserved at all times during component refactoring or extension to ensure consistency. diff --git a/guides/v2.2/coding-standards/technical-guidelines.md b/guides/v2.2/coding-standards/technical-guidelines.md index 2b545cf6ab2..79137291b1c 100644 --- a/guides/v2.2/coding-standards/technical-guidelines.md +++ b/guides/v2.2/coding-standards/technical-guidelines.md @@ -532,7 +532,77 @@ class View extends Template ### 6.4. Service Contracts (Application) layer -We are reviewing this section and will publish it soon. +6.4.1. Location of API interfaces + +6.4.1.1. Service contract interfaces SHOULD be placed in separate API modules. The other modules will depend on the API module, and implementations could be easily swapped via `di.xml`. API module namess must end with the `Api` suffix. For example, if a module is named `MyModule`, its APIs SHOULD be declared in a module named `MyModuleApi`. + +6.4.1.2. Service interfaces that should be exposed as web APIs MUST be placed under the `MyModuleApi/Api` directory. Service data interfaces MUST be placed under `MyModuleApi/Api/Data`. Directories under `MyModuleApi/Api` SHOULD NOT be nested. + +6.4.1.3. All other APIs, including explicit extension points such as Chain or Composite implementations, MUST be placed under `MyModuleApi/Model`. + +6.4.2. Service Interface Structure + +6.4.2.1. Methods that have similar names MUST serve similar purposes across different services, but they still MAY have different signatures. + +6.4.2.2. Service contracts SHOULD NOT be used for read scenarios on the storefront. Instead, GraphQL SHOULD be used for storefront scenarios. Check out [web API technical vision]({{ page.baseurl }}/coding-standards/technical-vision/webapi.html) for more details. + +6.4.2.3. Each service interface SHOULD declare a single public method. An interface name SHOULD reflect the task or action to be performed. For example, `Magento\InventoryApi\Api\StockSourceLinksDeleteInterface::execute(array $links)`. The only exception is a Repository API, which MAY be added for convenience and MUST be limited to singular CRUD operations and `getList($searchCriteria)`. + +6.4.3. Service Method Signature + +6.4.3.1. Strict typing is enforced for Service and Data interfaces located under `MyCompany/MyModuleApi/Api`. Only the following types are allowed: + +* Scalar types: `string` (including Date and DateTime); `int`; `float`; `boolean` + +* Data interfaces + +* One-dimensional indexed arrays of scalars or data interfaces: for example `string[]`, `\MyCompany\MyModuleApi\Api\Data\SomeInterface[]`. Hash maps (associative arrays) are not supported. + +* Nullable scalars or data interfaces: for example `string|null`. Using just `null` is prohibited. + +* `void` + +6.4.3.2. Service contracts SHOULD support batch data processing. For example, an entity persisting method SHOULD accept an array of entities to persist instead of a single entity. Customizations implemented through plugins SHOULD be adjusted respectively. + +6.4.3.3. Batch retrieval operations MUST accept `SearchCriteriaInterface` and return `SearchResultInterface` to support pagination. + +6.4.3.4. Batch operations that modify state MUST accept an array of entities and return a response object that contains: + +* An array of successfully processed items + +* An array of items with retriable errors + +* An array of items with non-retriable errors + +6.4.3.5. Batch operations that modify state SHOULD be implemented in the most performant manner and SHOULD NOT load modified entities to generate response. + +6.4.3.6. Asynchronous invocation of the command services SHOULD be supported by the web API framework. + +6.4.3.7. Operation UUID MAY be provided by the client during service invocation. UUID MUST allow the client to get the operation status information. + +6.4.3.8. Data objects returned by service contracts SHOULD be fully loaded to ensure consistency. + +6.4.4. Service Implementation + +6.4.4.1. Service data interfaces SHOULD extend from `Magento\Framework\Api\ExtensibleDataInterface`. The only exception is when extensibility is not desired, such as in case of value-objects. + +6.4.4.2. Extensible data interfaces MUST NOT form hierarchies. If interface `MyInterface` extends `ExtensibleDataInterface`, there must be no interfaces extending `MyInterface`. Otherwise, a list of extension attributes will be shared for all extensible interfaces in the hierarchy. + +6.4.4.3. Service implementations and plugins MUST NOT rely on storage-specific integrity features, such as foreign key constraints. + +6.4.4.4. Replacement strategy SHOULD be used to persist main entity fields/attributes, child entities, and relation links. + +6.4.4.5. During update operations, web APIs using the`PATCH` HTTP method and all action controllers that accept entities SHOULD pre-load them first, then merge the request data, and provide the full data to the service. + +6.4.4.6. If a service method needs to modify the argument, the original argument object MUST NOT be modified and its copy SHOULD be modified instead. + +6.4.4.7. Services SHOULD NOT apply ACL rules to methods or returned data. + +6.4.4.8. If a store has multiple scopes (websites, stores), then each call MUST persist an entity in a single scope only. If an entity needs to be saved in multiple scopes, then multiple calls SHOULD be made. + +6.4.4.9. Service contracts SHOULD NOT apply presentation layer formatting to the returned data. + +6.4.4.10. Service data interfaces MUST NOT contain any business logic. They SHOULD represent a container of data that is transferable over the wire. All the business logic SHOULD be moved to services. ## 7. Configuration diff --git a/guides/v2.2/coding-standards/technical-vision/index.md b/guides/v2.2/coding-standards/technical-vision/index.md new file mode 120000 index 00000000000..dfa7fadb840 --- /dev/null +++ b/guides/v2.2/coding-standards/technical-vision/index.md @@ -0,0 +1 @@ +../../../v2.1/coding-standards/technical-vision/index.md \ No newline at end of file diff --git a/guides/v2.3/coding-standards/technical-vision/index.md b/guides/v2.3/coding-standards/technical-vision/index.md new file mode 120000 index 00000000000..c6333c3dc6c --- /dev/null +++ b/guides/v2.3/coding-standards/technical-vision/index.md @@ -0,0 +1 @@ +../../../v2.2/coding-standards/technical-vision/index.md \ No newline at end of file