Question

If I intend to create a set of API that will allow other developers to interact with my application, how should I structure this set of API in the sense of packaging?

I am considering this…
For all the classes that runs my actual application, I have them in com.app.core
So for all features of my actual application, I have them in com.app.core.products, com.app.core.events, com.app.core.views, com.app.core.accounts, etc.

Then subsequently for the set of API classes, I put them in com.app.events, com.app.accounts, com.app.utils, etc.

Is this a good practise?

I’ve found this very weird in a few ways.
First, the core package is open to all. People can still access the core package objects directly, bypassing the API.

Second, I am having repetitive packages both in the ‘core’ package and in the outer package which serves as the API packages. For instance, com.app.core.accounts consists of all the classes the main application uses to operate its accounts module and com.app.accounts is an set of API classes for other developers to work from.

Third, if having repetitive packages is fine and is the right way to do so, then why wouldn’t I simply let anyone access directly to the com.app.core package and I don’t have repetitive folders and also the core package is accessible anyway?

What could have been a better way to do this? I working in Java and pretty new to this idea of creating my own API.

Thanks.

Answer 1

In my opinion those ‘repetitive’ packages are not a problem. They are just packages after all. The developer that works with your API only only sees them.

Also it’s not necessarily a problem that the developer can access your implementation classes. It’s the same with Java itself: There are a lot of com.sun classes that can be used but that doesn’t mean that you should. It makes porting to another Java runtime difficult.

It also depends a bit on the project. If you work with an architecture that cleanly separates the API from the implementation, the user of your API can’t access the implementation. OSGi and Web services come to mind. In this case you can create two different libraries: the implementation and the API with the implementation depending on the API. The API contains all classes that are important for external users. That way separation is quite easy.

The third problem doesn’t really exist. You can have different libraries that provide classes for the same packages. As long as you control the namespace and don’t have duplicate classes in the same package everything is fine. A package is just a name, nothing else.