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 Projectand 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:

Dynamic Web project

  • 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:

web service project components

  • 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:

web service controller

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

web service data access layer

  • exceptions: holds all the business exception classes of the application which are returned between components when a business exception occurs.

web service exception layer

  • helpers: holds all the utility classes which contains common functionalities to be used by all components.

web service utility layer

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

web service network layer

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

web service business layer

3. Web service configuration

The configuration of the web service is normally defined under config folder as either .properties or .xml files.

web service configuration

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.

web service unit tests

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.


0 0 votes
Article Rating

Hussein Terek

Owner of programmergate.com, I have a passion for software engineering and everything related to Java environment.

Newest Most Voted
Inline Feedbacks
View all comments
3 years ago

Great article ! Thanks for sharing

Jack Chalouhy
Jack Chalouhy
3 years ago

Thank you