@RequestMapping

#Introduction

@RequestMapping is the heart of Spring MVC. Without it, Spring has no idea which controller method should run for an incoming request.

#What is @RequestMapping?

@RequestMapping maps an HTTP request to a controller or controller method.

@RestController
@RequestMapping("/users")
public class UserController {
}

This tells Spring: every request starting with /users belongs to this controller.

Basic Example

@RestController
@RequestMapping("/users")
public class UserController {

    @RequestMapping("/all")
    public List<User> getUsers() {
        return List.of();
    }
}

GET /users/all matches this method.

#Internal Working

When your application starts, Spring performs:

It creates an internal routing table:

This table is maintained by RequestMappingHandlerMapping.

#Who Stores URL Mappings?

During startup Spring creates RequestMappingHandlerMapping. Its job:

When a request arrives:

Request Lifecycle

#Class-Level + Method-Level Mapping

A class-level mapping makes every method start with that prefix:

@RestController
@RequestMapping("/users")
public class UserController {

    @RequestMapping("/all")
    public List<User> all() {
        return List.of();
    }
}

Multiple Methods

@RestController
@RequestMapping("/users")
public class UserController {

    @RequestMapping("/all")
    public List<User> all() {}

    @RequestMapping("/active")
    public List<User> active() {}

    @RequestMapping("/blocked")
    public List<User> blocked() {}
}

#HTTP Methods

GET /users means read users.

Specifying the HTTP Method

@RequestMapping(value = "/users", method = RequestMethod.GET)
public List<User> users() {
}

Only GET requests can call this method.

@RequestMapping(value = "/users", method = RequestMethod.POST)
public User create() {
}

POST /users matches; GET /users does not (Spring answers 405 Method Not Allowed if nothing else matches).

#Why Use @GetMapping?

Instead of @RequestMapping(method = RequestMethod.GET), Spring 4.3 introduced shortcuts: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping and @PatchMapping.

@GetMapping("/users")

// equals

@RequestMapping(value = "/users", method = RequestMethod.GET)

Same behaviour, cleaner syntax.

#path vs value

These are identical — value and path are aliases:

@RequestMapping("/users")
@RequestMapping(value = "/users")
@RequestMapping(path = "/users")

#Multiple URLs

One method can serve multiple URLs:

@GetMapping({"/users", "/employees", "/customers"})
public String test() {
}

Any of these URLs invokes the same method.

#Narrowing the Match

params

@GetMapping(value = "/users", params = "active=true")
public List<User> active() {
}

Matches GET /users?active=true; does not match GET /users.

headers

@GetMapping(value = "/users", headers = "X-Version=1")

Only requests containing the header X-Version: 1 match. Useful for API versioning.

consumes

Defines which request content type is accepted:

@PostMapping(value = "/users", consumes = "application/json")

A request with Content-Type: application/json works; text/plain returns 415 Unsupported Media Type.

produces

Defines the response type:

@GetMapping(value = "/users", produces = "application/json")

Spring returns Content-Type: application/json. If the client's Accept header can't accept it, Spring returns 406 Not Acceptable.

Complete Example

@PostMapping(
        value = "/users",
        consumes = "application/json",
        produces = "application/json")
public User create(@RequestBody User user) {
    return user;
}

#URL Matching Priority

@GetMapping("/users/{id}")
@GetMapping("/users/all")

For GET /users/all, Spring prefers /users/all, because exact (more specific) matches have higher priority than path-variable matches.

#Ambiguous Mapping

❌ Wrong:

@GetMapping("/users")
public void get() {
}

@GetMapping("/users")
public void get2() {
}

Application startup fails:

IllegalStateException: Ambiguous mapping. Cannot map 'userController' method ...

Spring doesn't know which method should run. Never define two methods with an identical path + HTTP method combination.

#Real Project Example

@RestController
@RequestMapping("/employees")
public class EmployeeController {

    @GetMapping
    public List<Employee> all() {}

    @GetMapping("/{id}")
    public Employee get() {}

    @PostMapping
    public Employee save() {}

    @PutMapping("/{id}")
    public Employee update() {}

    @DeleteMapping("/{id}")
    public void delete() {}
}

#Internal Spring Flow

#Key Takeaways

• @RequestMapping is the foundation of Spring MVC URL routing.
• RequestMappingHandlerMapping discovers and stores mappings during startup.
• Class-level and method-level mappings combine to form the final endpoint.
• @GetMapping, @PostMapping, … are shortcuts built on @RequestMapping.
• Use consumes, produces, params and headers for precise matching.
• Duplicate mappings cause startup failures.