Merge pull request #3421 from magento-architects/kh_tech-vision

Added service contract technical guidelines

Author: keharper

_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

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.

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.

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
 

guides/v2.2/coding-standards/technical-vision/index.md

@@ -0,0 +1 @@
+../../../v2.1/coding-standards/technical-vision/index.md

guides/v2.3/coding-standards/technical-vision/index.md

@@ -0,0 +1 @@
+../../../v2.2/coding-standards/technical-vision/index.md