Introduction

In Spring Boot, mapping multiple URLs to the same controller method is straightforward. The mapping annotations accept an array of paths, so one handler can respond to several aliases without duplicating logic.

This is useful when you are preserving old routes during a migration, supporting shorthand and verbose paths, or exposing equivalent endpoints for backward compatibility. The important design decision is whether those routes should truly behave as aliases or whether one should redirect to a canonical URL.

The Basic Pattern

You can declare multiple paths in @RequestMapping, @GetMapping, @PostMapping, and similar annotations.

1import org.springframework.web.bind.annotation.GetMapping;
2import org.springframework.web.bind.annotation.RestController;
3
4@RestController
5public class HelloController {
6
7    @GetMapping({"/hello", "/hi", "/greet"})
8    public String hello() {
9        return "hello";
10    }
11}

All three paths call the same method.

Use @RequestMapping for Shared Method Types

If the handler should support multiple paths and a specific HTTP method configuration, @RequestMapping works the same way.

1import org.springframework.web.bind.annotation.RequestMapping;
2import org.springframework.web.bind.annotation.RequestMethod;
3import org.springframework.web.bind.annotation.RestController;
4
5@RestController
6public class UserController {
7
8    @RequestMapping(path = {"/users", "/members"}, method = RequestMethod.GET)
9    public String listUsers() {
10        return "users";
11    }
12}

This is useful when you want explicit control over method type or want to keep style consistent across a codebase.

Combine Class-Level and Method-Level Paths

Aliases also work with class-level mappings.

1import org.springframework.web.bind.annotation.GetMapping;
2import org.springframework.web.bind.annotation.RequestMapping;
3import org.springframework.web.bind.annotation.RestController;
4
5@RestController
6@RequestMapping({"/api", "/v1"})
7public class ProductController {
8
9    @GetMapping({"/products", "/items"})
10    public String products() {
11        return "products";
12    }
13}

This generates multiple effective routes such as /api/products, /api/items, /v1/products, and /v1/items.

That flexibility is powerful, but it can also create more route surface than you intended, so use it carefully.

When Aliases Are Better Than Redirects

Use true aliases when the routes are genuinely interchangeable and clients should be able to call any of them directly.

Use redirects when one URL is the canonical route and the others are legacy entry points. In that case, a controller or filter that returns a redirect may be better than silently serving multiple permanent endpoint forms forever.

For browser-facing routes, redirects often make the URL space cleaner. For API compatibility, multiple mappings are often the more practical choice.

Keep Path Variables Consistent

If aliased routes include path variables, keep the structure compatible.

1@GetMapping({"/users/{id}", "/members/{id}"})
2public String userById(@PathVariable String id) {
3    return id;
4}

The variable names and positions should line up. If one alias has a different structure, the shared method can become confusing quickly.

Avoid Alias Sprawl

Multiple mappings are easy to add, which makes them easy to overuse. Every alias becomes another route you may need to document, test, secure, and preserve.

Before adding three or four names for the same endpoint, ask whether you are solving a genuine compatibility problem or just avoiding a naming decision.

Common Pitfalls

A common mistake is creating many aliases without defining a canonical route. Over time, the API surface becomes harder to document and reason about.

Another mistake is combining class-level and method-level path arrays and accidentally generating more endpoint combinations than intended.

Developers also forget that aliases share the same handler logic. If one alias is meant to behave differently, it probably should not be an alias at all.

Finally, if backward compatibility is the goal, test security rules, interceptors, and documentation for every alias rather than assuming they all behave identically automatically.

Summary

• Spring Boot mapping annotations accept multiple paths as an array.
• '@GetMapping({"/a", "/b"}) is the simplest way to create URL aliases.'
• Class-level and method-level path arrays combine, which can be useful or excessive depending on the design.
• Use true aliases for equivalent routes and redirects when one canonical URL should win.
• Keep aliases intentional, documented, and limited so the route space stays maintainable.