Skip to content
BSWEN
Blog

Should You Separate Controllers for Internal and External APIs in Spring Boot?

Cowrie
Cowrie
Dev @ Bswen

Problem

When I started building a Spring Boot microservice with APIs accessed by external users through an API gateway and internal services calling each other directly, I ran into an organizational dilemma: Should I organize controllers by access type or by domain?

My first thought was to separate them clearly: external endpoints for public access, internal endpoints for service-to-service communication. But I was worried about code duplication and maintainability.

Environment

  • Spring Boot 3.2
  • Java 21
  • Spring Security 6
  • Spring Cloud Gateway

The Two Approaches

I considered two ways to organize my controllers.

Option A: Separate by Access Type

Package Structure (Option A)
/controllers
  /external
    - UserController.java
    - OrderController.java
  /internal
    - ServiceUserController.java
    - ServiceOrderController.java

This seemed appealing at first because it clearly separates public from private endpoints. I could easily see which endpoints were meant for external users versus internal services.

But I noticed problems immediately. When I needed to add a new feature to user management, I had to update two controllers. Business logic started duplicating between UserController and ServiceUserController.

Option B: Separate by Domain

Package Structure (Option B)
/controllers
  /user
    - UserController.java
  /order
    - OrderController.java

This approach groups endpoints by business domain. Both internal and external endpoints live in the same controller.

Why Domain-First Matters

I tried Option A first and quickly ran into issues.

When I added validation logic to create users, I had to duplicate the code in both controllers:

ExternalUserController.java
@RestController
@RequestMapping("/api/v1/users")
public class ExternalUserController {


    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody CreateUserRequest request) {
        validateUserRequest(request); // Validation logic here
        User user = userService.create(request);
        return ResponseEntity.ok(toResponse(user));
    }
}
InternalUserController.java
@RestController
@RequestMapping("/internal/v1/users")
public class InternalUserController {


    @PostMapping
    public ResponseEntity<UserEntity> createUserInternal(@RequestBody CreateUserRequest request) {
        validateUserRequest(request); // Same validation logic duplicated
        User user = userService.create(request);
        return ResponseEntity.ok(user);
    }
}

This violated the DRY principle and made maintenance painful. Every change required updating both files.

I switched to Option B and kept related logic together:

UserController.java
@RestController
@RequestMapping("/api/v1/users")
public class UserController {


    // External endpoints (via API gateway)
    @GetMapping
    @PreAuthorize("hasRole('USER')")
    public ResponseEntity<List&lt;UserResponse&gt;&gt; getUsers() {
        return ResponseEntity.ok(userService.findAll().stream()
            .map(this::toResponse)
            .toList());
    }


    @PostMapping
    @PreAuthorize("hasRole('USER')")
    public ResponseEntity<UserResponse> createUser(@RequestBody CreateUserRequest request) {
        validateUserRequest(request);
        User user = userService.create(request);
        return ResponseEntity.ok(toResponse(user));
    }


    // Internal endpoints (service-to-service)
    @GetMapping("/internal/{id}")
    @PreAuthorize("hasRole('SERVICE')")
    public ResponseEntity<UserEntity> getUserInternal(@PathVariable String id) {
        return ResponseEntity.ok(userService.findById(id));
    }


    @GetMapping("/internal/batch")
    @PreAuthorize("hasRole('SERVICE')")
    public ResponseEntity<List&lt;UserEntity&gt;&gt; getUsersBatch(@RequestParam List&lt;String&gt; ids) {
        return ResponseEntity.ok(userService.findByIds(ids));
    }
}

Now all user-related logic stays in one place. I only duplicate when necessary - like using different response types (DTO vs entity).

URL Path Strategies

The key insight is that URL paths provide the separation, not controller classes.

Here’s the convention I adopted:

URL Convention
External API:  /api/v1/{resource}
Internal API:  /internal/v1/{resource}
Health:        /actuator/**

This serves several purposes:

  1. Clear access boundaries for security configuration
  2. Easy API gateway routing - route /api/** externally, block /internal/**
  3. Documentation clarity - Swagger/OpenAPI can group by path prefix

Security Configuration

I configured security by path pattern, not by controller class:

SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {


    @Bean
    public SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/v1/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().hasRole("USER")
            )
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
        return http.build();
    }


    @Bean
    public SecurityFilterChain internalSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/internal/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().hasRole("SERVICE")
            );
        return http.build();
    }
}

This approach uses separate security filter chains. External endpoints require user authentication via JWT, while internal endpoints require service authentication.

API Gateway Integration

The API gateway configuration became straightforward:

application.yml
spring:
  cloud:
    gateway:
      routes:
        - id: external-api
          uri: lb://user-service
          predicates:
            - Path=/api/v1/**
          filters:
            - RateLimit=100,1s
            - JwtAuth
        # Internal routes are NOT exposed through gateway

I explicitly only expose /api/** paths. The /internal/** paths are accessible only within the service mesh or private network.

When Separate Controllers Make Sense

After using domain-organized controllers for a while, I found scenarios where separate controllers were actually justified.

  1. Completely different contracts - When internal API returns full entities and external API returns strictly formatted DTOs
  2. Different authentication mechanisms - OAuth for external, mutual TLS for internal
  3. Different rate limiting - Strict limits for external, relaxed for internal
  4. Different versioning strategies - Slow, backward-compatible versioning for external, fast iteration for internal

For example:

ExternalUserController.java
@RestController
@RequestMapping("/api/v1/users")
public class ExternalUserController {
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable String id) {
        User user = userService.findById(id);
        return ResponseEntity.ok(UserResponse.builder()
            .id(user.getId())
            .name(user.getName())
            .email(user.getEmail())
            // Only exposed fields
            .build());
    }
}
InternalUserController.java
@RestController
@RequestMapping("/internal/v1/users")
public class InternalUserController {
    @GetMapping("/{id}")
    public ResponseEntity<UserEntity> getUserRaw(@PathVariable String id) {
        // Returns full entity with internal fields
        return ResponseEntity.ok(userService.findById(id));
    }
}

In this case, the controllers serve fundamentally different purposes and audiences. The business logic still lives in the service layer, so no duplication occurs.

Common Mistakes I Made

Here are mistakes I encountered and how I fixed them.

Mistake 1: Organizing by Access Type

I initially created separate packages for external and internal controllers. This scattered related logic across the codebase.

WRONG - Access-based organization
/external/UserController.java
/internal/UserController.java

The fix: Organize by domain regardless of access type.

CORRECT - Domain-based organization
/user/UserController.java

Mistake 2: Duplicating Business Logic

I put business logic directly in controllers and duplicated it between external and internal versions.

The fix: Extract to a shared service layer. Controllers should be thin wrappers that handle HTTP concerns only.

Mistake 3: Mixing Internal and External in Same Endpoint

I tried to handle both cases in one endpoint with a header check:

WRONG - Don't do this
@GetMapping("/{id}")
public ResponseEntity&lt;?&gt; getUser(@PathVariable String id,
                                    @RequestHeader("X-Internal") boolean internal) {
    if (internal) return ResponseEntity.ok(entity);
    return ResponseEntity.ok(dto);
}

This creates unclear behavior and security risks. Separate the endpoints by path.

Mistake 4: Exposing Internal Endpoints Through Gateway

I almost exposed /internal/** paths through the API gateway by mistake.

The fix: Explicitly only route /api/** paths. Use network policies as an additional layer of security.

Practical Implementation

Here’s my complete approach for implementing domain-organized controllers with clear access boundaries.

Step 1: Define URL Constants

ApiPaths.java
public class ApiPaths {
    public static final String EXTERNAL_PREFIX = "/api/v1";
    public static final String INTERNAL_PREFIX = "/internal/v1";
}

Step 2: Configure Separate Security Chains

SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {


    @Bean
    public SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/v1/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().hasAuthority("SCOPE_user")
            )
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt)
            .csrf(AbstractHttpConfigurer::disable);
        return http.build();
    }


    @Bean
    public SecurityFilterChain internalSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/internal/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().hasAuthority("SCOPE_service")
            )
            .csrf(AbstractHttpConfigurer::disable);
        return http.build();
    }
}

Step 3: Document with OpenAPI

ExternalApiConfig.java
@OpenAPIDefinition(
    info = @Info(title = "User Service API", version = "1.0"),
    group = "external"
)
public class ExternalApiConfig { }
InternalApiConfig.java
@OpenAPIDefinition(
    info = @Info(title = "User Service Internal API", version = "1.0"),
    group = "internal"
)
public class InternalApiConfig { }

Step 4: Add Metrics

MetricsConfig.java
@Configuration
public class MetricsConfig {
    @Bean
    public TimedAspect timedAspect(MeterRegistry registry) {
        return new TimedAspect(registry);
    }
}
UserController.java (metrics annotation)
@Timed(value = "api.users", extraTags = {"access", "external"})
@GetMapping("/api/v1/users")
public ResponseEntity<List&lt;UserResponse&gt;&gt; getUsers() { ... }

Summary

In this post, I showed how to organize Spring Boot controllers by domain rather than access type. The key points are:

  1. Organize controllers by business domain, keeping related endpoints together
  2. Use URL path prefixes (/api/v1/* vs /internal/*) to separate access boundaries
  3. Configure security by path pattern, not by controller class
  4. Consider separate controllers only when contracts fundamentally differ
  5. Extract business logic to service layer to avoid duplication

This approach keeps related code together while maintaining clear boundaries between public and private endpoints. It scales well as services grow and makes the codebase easier to navigate and maintain.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: