Web service project structure
In this article we introduce the most common way for structuring a maintainable web service, our example can be used as a template for creating any web service using object oriented language. The important factor when structuring an application is to divide it into several modules/components and to define how these components interact between each other.
The following example is about a java API which charges customers for serving them some product.
P.S: The IDE used throughout this tutorial is Eclipse Mars.
1. Root structure
Create a new dynamic web project: File -> New -> Other -> Dynamic Web Project, and name it as charging-service. By default, the project holds src, WebContent and build folders.
In order to organize our project, we added some other folders so that the root structure looks like the following:
- src: holds the different components of the application and the source code.
- config: holds all the static configuration files used by the application like: database, logging and application properties.
- junit: holds all the unit test classes of the application.
- scripts: holds all the database modification scripts since the first release.
- WebContent: holds the external libraries and web application configuration.
2. Web service components
Each component of the application is defined as a package inside the src folder where com.charging.service is the root package, following are the most common components for any web service:
- controller: This component holds all the controllers which are exposed to the clients, each client should have its own controller along with its own request and response DTOs just like the following:
- db: This component takes care of the database communication, normally it is exposed to other components through an abstract interface, it holds the database interface class, the data access objects, and the different database access implementations.
- exceptions: holds all the business exception classes of the application which are returned between components when a business exception occurs.
- helpers: holds all the utility classes which contains common functionalities to be used by all components.
- network: This is the component which takes care of the interaction with external APIs or services, normally it exposes an abstract interface to other components.
- processor: This is the business component which holds the business details of the application, normally it exposes an abstract interface to other components in order to hide the several business implementations and for supporting separate business for each client.
3. Web service configuration
The configuration of the web service is normally defined under config folder as either .properties or .xml files.
This makes it easier to change the configuration dynamically while the service is up without the need to restart it.
4. Web service unit tests
The junit folder normally holds the same components defined under src folder, we normally define a test class for each component and a general test class which tests the integration between all components, this general test class is used to test the full application functionalities.
As shown in the example, this structure defines a loosely coupled web service which forces its components to only communicate using abstract interfaces, hence makes it open for extension in the future.