Added service contract technical guidelines

_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,7 @@
+---
+group: coding-standards
+title: Magento technical vision
+---
+
+A collection of component technical vision documents describes the desired state of Magento product.
+Each individual technical vision relates to a set of modules logically grouped together. Technical vision typically describes component's place in the system, its architecture, extension scenarios and a list of invariants which 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,7 @@
+---
+group: coding-standards
+title: Magento technical vision
+---
+
+A collection of component technical vision documents describes the desired state of Magento product.
+Each individual technical vision relates to a set of modules logically grouped together. Technical vision typically describes component's place in the system, its architecture, extension scenarios and a list of invariants which 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,75 @@ class View extends Template
 
 ### 6.4. Service Contracts (Application) layer
 
-We are reviewing this section and will publish it soon.
+6.4.1. Location
+
+6.4.1.1. Service contract interfaces should be placed in separate API modules. All other modules will depend on the API module, while implementations could be easily swapped via `di.xml`. For example, if module is named `MyModule`, its APIs should be declared in the module named `MyModuleApi`.
+
+6.4.1.2. Service interfaces which should be exposed as web APIs must be placed under `MyModuleApi/Api/Service` directory. Service data interfaces must be placed under `MyModuleApi/Api/Data`. 
+
+6.4.1.3. All other APIs, including explicit extension points like Chain or Composite implementations must be placed under `MyModuleApi/Model`. 
+
+6.4.1.4. Arbitrary directory nesting can be used for APIs to improve code structure. For example, `MyCompany\MyModuleApi\Api\Service\Relations\DeleteInterface`.
+
+6.4.2. Types Hierarchy
+
+6.4.2.1. If service data interface should be extensible, it must extend from `Magento\Framework\Api\ExtensibleDataInterface`.
+
+6.4.2.1. Extensible data interfaces must not form hierarchies. Extension attributes do not work for child extensible interfaces.
+
+6.4.3. Service Interface Structure
+
+6.4.3.1. Methods named similarly must serve similar purpose across different services, but still might have different signatures.
+
+6.4.3.2. Services must only operate on scalar types or service data interfaces.
+
+6.4.3.3. Service contracts should not be used for read scenarios on the storefront, GraphQL should be used for storefront scenarios instead. Check out [web API technical vision]({{ page.baseurl }}/coding-standards/technical-vision/webapi.html) for more details.
+
+6.4.3.4. Each service interface should declare a single public method. Interface name should reflect task/action to be performed. Example `Magento\InventoryApi\Api\StockSourceLinksDeleteInterface::execute(array $links)`. The only exception is Repository API which may be added for convenience and must be limited to singular CRUD operations and `getList($searchCriteria)`.
+
+6.4.4. Service Method Signature
+
+6.4.4.1. Service contracts should not apply presentation layer formatting to the returned data.
+
+6.4.4.2. Service data interfaces represent domain entities and can reference related data interfaces.
+
+6.4.4.3. Service data interfaces must be implemented as DTOs with a set of symmetric getters and setters.
+
+6.4.4.3. 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
+
+* Optional scalars or data interfaces: `string|null`. It is prohibited to use just `null`
+
+6.4.4.4. Service contracts should support batch data whenever possible. For example, entity persisting interface should accept an array of entities to persist instead of a single entity. Customizations via plugins must be adjusted respectively. Batch retrieval operations must accept `SearchCriteriaInterface` and return `SearchResultInterface` to support pagination.
+
+6.4.4.5. Command operations (the ones which modify the state) must support asynchronous execution. Void must be used as return type, the status of the operation may be checked by polling of the respective query operation. Create operations must support UUID generated on the client side.
+
+6.4.4.6. Command operations (the ones which modify the state) must support asynchronous execution. Void must be used as return type, the status of the operation may be checked by polling of the respective query operation. Create operations must support UUID generated on the client side.
+
+6.4.4.7. Data objects returned by service contracts should be fully loaded to ensure consistency.
+
+6.4.5. Service Implementation
+
+6.4.5.1. Service implementations and plugins must not rely on storage-specific integrity features, such as foreign key constraints.
+
+6.4.5.2. Replace strategy should be used to persist main entity fields/attributes, child entities and relation links. 
+
+6.4.5.3. During update operations, Web APIs with `PATCH` HTTP method and all action controllers that accept entities should pre-load them first, merge request data on top of that and provide full data to service.
+
+6.4.5.4. If service method needs to return a modified version of the argument, the original argument object must not be modified and its copy should be modified and returned instead.
+
+6.4.5.5. Services should not apply ACL rules to methods or returned data.
+
+6.4.5.6. If multiple data scopes available, within one service call entity should be persisted only for one specific data scope.
+
+6.4.6. Exception Handling
+
+6.4.6.1. Service methods must only throw exceptions defined as part of service contract layer. Exceptions thrown from lower layers should not be exposed outside and must be wrapped with appropriate service contract layer exception.
 
 ## 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