Is it possible (recommended) to have a pure api-project that is separated from the actual implementation?

Question

I was asked to create a project-layout for our upcoming application using Maven. The first artefact we are going to work on will be the architecture. In order to make it as easy as possible for developers to work I got the idea to separate the actual implementation from the API (like you would do in a OSGi environment).

The dependencies would list the API-project as a dependency for the compile-scope and the implementation is only provided at runtime.

With this approach I am hoping to reduce the complexity for the developers and also restrain them from using internal classes that are frequent subject to change. Furthermore it is possible to hide transitive dependencies (e.g. I dont want the developers to call the DAO-layer from the frontend...this should only be visible from the service-layer).

Has someone put this into practice and how did it go? What do you think about it in general?

Answer 1

I have seen it a lot, and there are advantages and disadvantages to that approach:

• Advantages
  • Clear separation of API and implementation
• Disadvantages
  • More difficult to understand, because there is no real context, example, unit tests to look at to understand the API.
  • More difficult to refactor, and to understand the consequences of API definition and changes. I am poor to imagine what may be a good API until I have used it (and seen that it does not work well).
  • If there is a (running) implementation behind your API that is not accessible to the people, it is difficult or even impossible to implement real test for the real application.

So I think it is nice to publish an API as API only, but it is difficult to develop the API without real source code, and sometimes to implement against the real API without running code that shows how it works.

Different approaches could be:

• Develop with the API a default implementation as showcase.
• Develop with the API an example implementation that shows how to use the API.
• Develop a set of unit tests and mock objects to show how to use your API in unit tests.

Answer 2

It's sound design to separate interface (contract) and implementation. But as with everything, use with moderation. You don't want to restrict and complicate the design to the point where it costs more than it delivers. Remember, it's supposed to add benefit (or lower risk), it's not a goal in itself. Ask yourself why you do these things, what the cost and benefit is and what the associated risk and/or cost of NOT doing it would be.