"Api" folder as the module gateway

[adragus-inviqa]

I just wanted to clarify if I'm going against M2's convention regarding the Api folder here.

The docs say that the Api folder contains any PHP classes exposed to the API.

Mainly, this folder has interfaces in it, which is a good thing.

But 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.

But, 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.

Developers 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.

Is 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?

PS: I know about the @api docblock. No.
PPS: I know others can override the default implementation via di.xml.

[alankent]

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.)

At 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.

So, 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.

Note: 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.

[antonkril]

We don't have another standard directory for non-service api.

Also we avoid making implementations public because modules should only communicate by interfaces, Implementations should be private to discourage inheritance from implementations.

[adragus-inviqa]

Thanks for clarifying. Interfaces in Api, and @api for everything else (hopefully none).