{"action":"created","issue":{"url":"https://api.github.com/repos/magento/magento2/issues/2122","labels_url":"https://api.github.com/repos/magento/magento2/issues/2122/labels{/name}","comments_url":"https://api.github.com/repos/magento/magento2/issues/2122/comments","events_url":"https://api.github.com/repos/magento/magento2/issues/2122/events","html_url":"https://github.com/magento/magento2/issues/2122","id":111661618,"number":2122,"title":"\"Api\" folder as the module gateway","user":{"login":"adragus-inviqa","id":13104649,"avatar_url":"https://avatars.githubusercontent.com/u/13104649?v=3","gravatar_id":"","url":"https://api.github.com/users/adragus-inviqa","html_url":"https://github.com/adragus-inviqa","followers_url":"https://api.github.com/users/adragus-inviqa/followers","following_url":"https://api.github.com/users/adragus-inviqa/following{/other_user}","gists_url":"https://api.github.com/users/adragus-inviqa/gists{/gist_id}","starred_url":"https://api.github.com/users/adragus-inviqa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/adragus-inviqa/subscriptions","organizations_url":"https://api.github.com/users/adragus-inviqa/orgs","repos_url":"https://api.github.com/users/adragus-inviqa/repos","events_url":"https://api.github.com/users/adragus-inviqa/events{/privacy}","received_events_url":"https://api.github.com/users/adragus-inviqa/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-10-15T16:59:11Z","updated_at":"2015-10-15T17:56:48Z","closed_at":null,"body":"I just wanted to clarify if I'm going against M2's convention regarding the `Api` folder here.\r\n\r\nThe [docs](http://devdocs.magento.com/guides/v2.0/extension-dev-guide/module-file-structure.html) say that the `Api` folder `contains any PHP classes exposed to the API`.\r\n\r\nMainly, this folder has interfaces in it, which is a good thing.\r\n\r\nBut currently I'm experimenting with this folder as being a sort of a easier-to-find \"gateway\" to module A. Say module B wants some functionality from module A, the B's developer just looks in the A's `Api` folder, _and only in there_. \r\n\r\nBut, sometimes, you want others to access _implementations_ of your module, not only interfaces. Like an interface with a default implementation. And I was thinking that the `Api` folder is the best place to put those implementations (not only interfaces and abstracts). I'm regarding that folder as `hey, 3rd party, look in \"Api\" and nowhere else; if it's in there, you can use it`. That means that, **even if it's a helper or model**, and I want others to use it **directly**, I'd put them in the `Api` folder. If it's something that I want to hide its implementation, I'd use an interface ofc, but, if I don't, I'd just put the implementation directly in there.\r\n\r\nDevelopers will have an easier time seeing what to use from that module and what no to use. Furthermore, because people have a sane aversion to putting implementations in anything named `Api`, they'll mostly have interfaces in it anyway.\r\n\r\nIs this the standard you're trying to convey with the `Api` folder? Is this an approach that you'd want that folder to be used? Convention-wise, would you have something against devs having models and/or concrete classes in the `Api` folder?\r\n\r\nPS: I know about the `@api` docblock. No.\r\nPPS: I know others can override the default implementation via `di.xml`."},"comment":{"url":"https://api.github.com/repos/magento/magento2/issues/comments/148472703","html_url":"https://github.com/magento/magento2/issues/2122#issuecomment-148472703","issue_url":"https://api.github.com/repos/magento/magento2/issues/2122","id":148472703,"user":{"login":"alankent","id":5702163,"avatar_url":"https://avatars.githubusercontent.com/u/5702163?v=3","gravatar_id":"","url":"https://api.github.com/users/alankent","html_url":"https://github.com/alankent","followers_url":"https://api.github.com/users/alankent/followers","following_url":"https://api.github.com/users/alankent/following{/other_user}","gists_url":"https://api.github.com/users/alankent/gists{/gist_id}","starred_url":"https://api.github.com/users/alankent/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alankent/subscriptions","organizations_url":"https://api.github.com/users/alankent/orgs","repos_url":"https://api.github.com/users/alankent/repos","events_url":"https://api.github.com/users/alankent/events{/privacy}","received_events_url":"https://api.github.com/users/alankent/received_events","type":"User","site_admin":false},"created_at":"2015-10-15T17:56:48Z","updated_at":"2015-10-15T17:56:48Z","body":"The goal of the Api directory is to list service contracts. Service contracts are interface definitions.  (At one stage it was called \"Services\", but it got renamed - we won't rename it back.)\r\n\r\nAt the moment, our convention is to put @api annotations only anything that others should be able to depend on. I would rather not mix that into the Api directory. We hit issues like plugins - if we want to say \"this function here you can define a plugin on\" then we would add an @api annotation to it. We would love to restrict this to a well known directory, but being pragmatic I bet we get requests \"please make function X stable\". If we agree, we add an @api annotation. I would not want to mandate all that sort of code to be pulled up to a parent directory.\r\n\r\nSo, let's keep \"Api\" for service contracts only (and \"web API bindings\").  Having another top level directory for other public API stuff makes sense - I don't recall if we have a standard around that - @antonkril?  But I personally doubt we can say \"that is the only public stuff\" due to plugins.\r\n\r\nNote: Extension developers are welcome to request @api annotations on functions that matter to them. We are trying to keep minimal, but if important we can review and add them."}}