Complete Guide to Setting Base URL for REST APIs in Spring Boot

Introduction

In modern web application development, RESTful APIs have become the standard architectural pattern. Spring Boot, as one of the most popular frameworks in the Java ecosystem, provides robust REST support. However, in practical projects, we often need to mix REST APIs with traditional MVC controllers and set unified base paths for REST endpoints.

Problem Context

When building Spring Boot applications, developers typically want REST controllers to be accessible through a unified base path (e.g., example.com/api), while MVC controllers maintain their original path structure. This requirement stems from the popularity of microservices architecture, where API gateways often need uniform prefixes to route requests.

The traditional approach involves using annotations like @RequestMapping("api/products") on each REST controller, but this leads to code duplication and maintenance difficulties. The ideal solution is to configure the base path in a single location, allowing controllers to define only relative paths.

Configuration Property Solutions

Spring Boot 1.2+ to 2.0 Versions

For versions between Spring Boot 1.2 and 2.0, the simplest method is to add the following configuration in the application.properties file:

spring.data.rest.basePath=/api

This configuration is specifically for Spring Data REST projects and automatically adds the /api prefix to all REST endpoints. For example, a controller originally mapped to /products can now be accessed via /api/products.

Spring Boot 2.x Versions

Starting from Spring Boot 2.0, the following configuration is recommended:

server.servlet.context-path=/api

This configuration is more universal, affecting not only REST controllers but the entire application's context path. This means all endpoints (including MVC controllers) automatically gain the /api prefix.

If you need to add a prefix only to REST controllers while keeping MVC controllers unchanged, a programmatic configuration approach is required.

Programmatic Configuration Approach

For more granular control, you can use the configurePathMatch method of the WebMvcConfigurer interface:

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.addPathPrefix("api", HandlerTypePredicate.forAnnotation(RestController.class));
    }
}

This method uses HandlerTypePredicate to precisely specify that only controllers annotated with @RestController should receive the path prefix. Thus, REST controllers automatically get the /api prefix, while ordinary @Controllers remain unchanged.

Version Compatibility Considerations

Different Spring Boot versions have variations in path configuration:

• Spring Boot 1.x: Use server.contextPath
• Spring Boot 2.x: Use server.servlet.context-path
• Spring Data REST: Use spring.data.rest.basePath

In practical projects, it's essential to choose the appropriate configuration method based on the Spring Boot version and components used.

Practical Application Scenarios

Referencing integration cases with the Camunda workflow engine highlights the importance of path configuration in real-world projects. When multiple web applications share the same Servlet context, proper path planning can prevent conflicts.

For example, in Camunda integration projects:

• /app - Camunda Web Application
• /rest - Camunda REST API
• /api - Custom Business APIs

This clear path division allows different functional endpoints to coexist harmoniously and facilitates routing by API gateways.

Best Practice Recommendations

Based on the above analysis, we recommend the following best practices:

1. Single Configuration Principle: Prefer unified configuration in application.properties to minimize code intrusion.
2. Version Adaptation: Select appropriate configuration properties according to the Spring Boot version.
3. Path Planning: Plan path prefixes for different functional modules in advance to avoid future conflicts.
4. Testing Validation: After configuration, always verify path mappings through unit tests and integration tests.

Conclusion

Spring Boot offers multiple flexible ways to set unified base paths for REST APIs. From simple property configurations to fine-grained programmatic control, developers can choose the most suitable solution based on specific needs. The key is understanding the scope and version compatibility of different configuration methods to ensure REST endpoints and MVC controllers can coexist harmoniously.

Through reasonable path planning, not only can code maintainability be improved, but it also lays a solid foundation for future microservices architecture evolution. In practical projects, it is advisable to select the most appropriate configuration strategy by considering the team's technology stack and business requirements.