Java Rest API Structure

Project structure

The outline structure of the project is as below.

β”‚ └───com
β”‚ └───xxAMIDOxx
β”‚ └───xxSTACKSxx
β”‚ β”œβ”€β”€β”€core
β”‚ β”‚ β”œβ”€β”€β”€api
β”‚ β”‚ β”‚ β”œβ”€β”€β”€dto
β”‚ β”‚ β”‚ β”œβ”€β”€β”€exception
β”‚ β”‚ β”‚ └───filter
β”‚ β”‚ β”œβ”€β”€β”€messaging
β”‚ β”‚ β”‚ β”œβ”€β”€β”€event
β”‚ β”‚ β”‚ └───publish
β”‚ β”‚ └───operations
β”‚ └───menu
β”‚ β”œβ”€β”€β”€api
β”‚ β”‚ β”œβ”€β”€β”€v1
β”‚ β”‚ β”‚ β”œβ”€β”€β”€controller
β”‚ β”‚ β”‚ β”œβ”€β”€β”€dto
β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€β”€request
β”‚ β”‚ β”‚ β”‚ └───response
β”‚ β”‚ β”‚ └───impl
β”‚ β”‚ └───v2
β”‚ β”‚ └───impl
β”‚ β”œβ”€β”€β”€domain
β”‚ β”œβ”€β”€β”€events
β”‚ β”œβ”€β”€β”€exception
β”‚ β”œβ”€β”€β”€mappers
β”‚ β”œβ”€β”€β”€repository
β”‚ └───service
β”‚ └───impl

Overview of com.xxAMIDOxx.xxSTACKSxx.core packages

The core.api package contains the request filter definitions (responsible for generating a correlation ID for every request), and the main Exception class from which all other custom exceptions in the code extend.

Package core.messaging contains the ApplicationEvent definition and default event publisher (events are published via a logger).

Package core.operations contains the OperationContext class that stores operation codes and correlation ID.

Overview of packages

Package menu.api.v1 contains the Controller definitions, both as interface definitions where the Swagger (OpenAPI) details are defined, and as concrete implementations under the impl package.

Package menu.api.v2 contains the Controller definitions for a simple V2 version of, both as interface definitions where the Swagger (OpenAPI) details defined, and as concrete implementations under the impl package.

Package menu.api.v1.dto contains request and response object definitions for the different endpoints.

Package menu.api additionally contains the OpenApiConfiguration class, which is responsible for defining what is displayed by the Swagger UI page for the application.

Package menu.commands contains the OperationCode class which holds codes for each operation, e.g. CREATE_MENU, UPDATE_CATEGORY etc.

Package menu.domain contains the data object defintions for the Menu model: Menu, Category and Item.

Package contains the Event definitions for specific API update events.

Package menu.exception contains the custom Exception definitions for the application.

Package menu.repository contains the MenuRepository interface definition, which defines repository operations and extends CosmosRepository, itself an extension of the Spring PagingAndSortingRepository.

Package menu.service contains the interface MenuQueryService and its implementation, CosmosMenuQueryService which relies on the CosmosRepository to fulfil the service's actions.


The resources directory contains an application.yaml file, and this is responsible for the project configuration. This information includes Azure Cosmos DB and Application Insights configuration, which are passed as a environment variables during the deployment phase.

Below is snippet of the application.yml configuring the Swagger and the Spring Boot specifications:

name: xxSTACKSxx-api
detection-strategy: annotated
# Note: ONLY use this if you're behind a trusted Reverse Proxy, such as Application Gateway.
# If you host this app directly then users can easily inject headers.
forward-headers-strategy: framework
port: 9000
base-path: /
disable-swagger-default-url: true
display-operation-id: true
path: /swagger/index.html
enabled: true
enabled: true
path: /swagger/oas-json

Application logging

Java provides a simple logging abstraction with most of required logging features used by an application. Whenever logging is required in the application, the class will instantiate an instance of Logger from slf4j to use as the logger object. The Logger instances are created by Logging Factory registered by each application and will abstract the logging library from the application logging.

In the application, we have customized how the logs are created. There is a logback-spring.xml file in the resources directory to add the customized features, as below:

<?xml version="1.0" encoding="UTF-8"?>
<appender class="ch.qos.logback.core.ConsoleAppender" name="console">
<pattern>%d{dd-MM-yyyy HH:mm:ss.SSS} %magenta([%thread]) | %X{CorrelationId} |
%highlight(%-5level) %logger{36}.%M - %msg%n
<appender class=""
<root level="debug">
<appender-ref ref="console"/>
<root level="info">
<appender-ref ref="aiAppender"/>

Application Insights

Azure Application Insights is the chosen logging platform, and will aggregate all logs generated by all services.

Integrating with Application Insights ensures all logs generated (and filtered) are forwarded to the logging platform for correlation and potential future investigation. Below is the section that needs to be added the application.yml to enable it to interact with Application Insights:

instrumentation-key: xxxxxx
enabled: true

We also need to add the SDK dependencies to the pom.xml file definitions:


Additionally, an AI-Agent.xml definition is included in the resource directory to enable deeper data insights:

<?xml version="1.0" encoding="utf-8"?>
<Logging threshold="info"/>

Any events published by the application will have a correlation id, to enable tracking of requests, responses and any exceptions.

Authorization with Auth0

The API endpoints are protected by an OAuth 2.0 provider. The OAuth 2.0 client is configured as an Auth0 instance. All requests must include a Bearer token in the Authorization header.

There is an file which configures the authorization definitions required to use the application with in conjunction with Auth0 to secure access to endpoints with JWT. If this property is set:


then a valid JWT is required to be sent with the header in the request to the API endpoint.

Other Auth0 properties defined in this file, and used by spring security for validating the token are:

  • auth0.issuer - the issuer of the JWT Token. Typically, this is your Auth0 domain prefixed by https://
  • auth0.apiAudience - the unique identifier for your API, https://.../api/v2/

Testing Auth0 JWT security using Swagger UI

  • Open the swagger UI page at http://localhost:9000/swagger/index.html once the application is up and running locally.

  • Send a POST request via the Auth endpoint on the Swagger UI page for your configured API definition, containing the following payload:

    "client_id": "REDACTED",
    "client_secret": "REDACTED",
    "audience": "https://REDACTED/api/v2/",
    "grant_type": "client_credentials"
  • You should receive a response containing a valid token something like

    "access_token": "eyJhbGciOiJSU...wd6WXw",
    "expires_in": 86400,
    "token_type": "Bearer"
  • Click on the Authorise button on the Swagger UI page and paste the token.

  • Endpoints should now work only with a valid token.