Technical guidelines: Clarify what to do when service contracts already exist in a module not suffixed with "Api" #3524
Conversation
|
|
|
@nathanjosiah thank you for contributing. Please accept Community Contributors team invitation here to gain extended permissions for this repository. |
|
An admin must run tests on this PR before it can be merged. |
keharper
added
2.x
Internal Dev
Co-Authored-By: nathanjosiah <[email protected]>
|
Doesn't this burden eventually moving existing contracts into an Api module? Wouldn't it be better to |
|
@buskamuza Is any additional architect review required? |
|
@buskamuza Can this be merged? |
|
Please don't merge yet. |
|
@buskamuza You closed magento/architecture#75 last week. Can this PR be merged? |
| @@ -536,7 +536,7 @@ class View extends Template | |||
|
|
|||
| 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.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. If contracts need to be added to support a module that already contains classes under `Api/` (e.g. `MyModule/Api`), the contracts SHOULD be added to the existing module. | |||
There was a problem hiding this comment.
I propose to add a note to 6.4.1.1. instead as that is the item describing the rules on a module level. So I'd rather rephrase that one as "6.4.1.1. Service contract interfaces SHOULD be placed in separate API modules , except when existing module already contains Service Contracts in Api folder. 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."
An important point here is that Api folder should contain Service Contracts (probably that's the only expected, but who knows).
|
@keharper , we close tickets just to indicate that it's a past meeting. |
keharper
added
Major Update
|
running tests |
|
running tests |
|
Hi @nathanjosiah, thank you for your contribution! |
This PR is a:
Summary
Re: https://devdocs.magento.com/guides/v2.3/coding-standards/technical-guidelines.html#64-service-contracts-application-layer
For the new service contract doc requirements, what should be done when new interfaces need to be added to a module that already has the contracts in the main module. For example, I need to add contracts to support
MyModulebutMyModule/Apialready exists. Should they be added toMyModule/Api? or should the contract locations be fragmented and create the new moduleMyModuleApi/Api/with the new contracts and leave theMyModule/Apicontracts as-is?More information regarding suggested change
My suggestion is to keep the contracts in the module rather than making a new module and deprecating the old contracts. This will prevent 3rd party devs from deprecating code and it also will simplify the development process for module that already have contracts. These modules can be migrated to the new form at a later time with specific direction when it makes sense in the project lifecycles (i.e. a major or minor release).
whatsnew
Added clarification about the location of Service Contracts in section 6.4.1.1 of the Technical Guidelines