Spring RequestMapping

I usually post about Spring stuff on Twitter - you can follow me there:

1. Overview

In this article, we will discuss one of the main annotations in Spring MVC – @RequestMapping – used to map web requests to Spring Controller methods.

Throughout the article, we will test each of the mappings showed via simple curl commands.

If you want to dig deeper into building a REST API with Spring – check out the main REST with Spring tutorial.

The Ins and Outs of Your Java Web Application

The Ins and Outs of Your Java Web Application

2. RequestMapping Basics

Let’s start with a simple example – mapping an HTTP request to a method using some straightforward criteria.

2.1. @RequestMapping – by Path

@RequestMapping(value = "/ex/foos")
public String getFoosBySimplePath() {
    return "Get some Foos";

To test out this mapping with a simple curl command, run:

curl -i http://localhost:8080/spring-rest/ex/foos

2.2. @RequestMapping – the HTTP Method

By default, the HTTP method mapped by a @RequestMapping is GET – this can of course be changed – for example to map to a POST request:

@RequestMapping(value = "/ex/foos", method = RequestMethod.POST)
public String postFoos() {
    return "Post some Foos";

To test the POST via a curl command:

curl -i -X POST http://localhost:8080/spring-rest/ex/foos

3. RequestMapping and HTTP Headers

3.1. @RequestMapping with the headers attribute

The mapping can be narrowed even further by specifying a header for the request:

@RequestMapping(value = "/ex/foos", headers = "key=val")
public String getFoosWithHeader() {
    return "Get some Foos with Header";

And even multiple headers via the header attribute of @RequestMapping:

@RequestMapping(value = "/ex/foos", headers = { "key1=val1", "key2=val2" })
public String getFoosWithHeaders() {
    return "Get some Foos with Header";

To test the operation, we’re going to use the curl header support:

curl -i -H "key:val" http://localhost:8080/spring-rest/ex/foos

Note that for the curl syntax for separating the header key and the header value is a colon, same as in the HTTP spec, while in Spring the equals sign is used.

3.2. @RequestMapping Consumes and Produces

Mapping media types produced by a controller method is worth special attention – we can map a request based on its Accept header via the @RequestMapping headers attribute introduced above:

@RequestMapping(value = "/ex/foos", method = GET, headers = "Accept=application/json")
public String getFoosAsJsonFromBrowser() {
    return "Get some Foos with Header Old";

The matching for this way of defining the Accept header is flexible – it uses contains instead of equals, so a request such as the following would still map correctly:

curl -H "Accept:application/json,text/html" http://localhost:8080/spring-rest/ex/foos

Starting with Spring 3.1, a the @RequestMapping annotation now has a produces and a consumes attributes, specifically for this purpose:

@RequestMapping(value = "/ex/foos", method = RequestMethod.GET, produces = "application/json")
public String getFoosAsJsonFromREST() {
    return "Get some Foos with Header New";

Also, the old type of mapping with the headers attribute will automatically be converted to the new produces mechanism starting with Spring 3.1, so the results will be identical.

This is consumed via curl in the same way:

curl -H "Accept:application/json" http://localhost:8080/spring-rest/ex/foos

Additionally, produces support multiple values as well:

@RequestMapping(value = "/ex/foos", produces = { "application/json", "application/xml" })

Keep in mind that these – the old way and the new way of specifying the accept header – are basically the same mapping, so Spring won’t accept them together – having both these methods active would result in:

Caused by: java.lang.IllegalStateException: Ambiguous mapping found. 
Cannot map 'fooController' bean method
public java.lang.String org.baeldung.spring.web.controller.FooController.getFoosAsJsonFromREST()
to {[/ex/foos],methods=[GET],params=[],headers=[],consumes=[],produces=[application/json],custom=[]}: 
There is already 'fooController' bean method
public java.lang.String org.baeldung.spring.web.controller.FooController.getFoosAsJsonFromBrowser() 

A final note on the new produces and consumes mechanism – these behave differently from most other annotations: when specified at type level, the method level annotations do not complement but override the type level information.

4. RequestMapping with Path Variables

Parts of the mapping URI can be bound to variables via the @PathVariable annotation.

4.1. Single @PathVariable

A simple example with a single path variable:

@RequestMapping(value = "/ex/foos/{id}")
public String getFoosBySimplePathWithPathVariable(@PathVariable("id") long id) {
   return "Get a specific Foo with id=" + id;

This can be tested with curl:

curl http://localhost:8080/spring-rest/ex/foos/1

If the name of the method argument matches the name of the path variable exactly, then this can be simplified by using @PathVariable with no value:

@RequestMapping(value = "/ex/foos/{id}")
public String getFoosBySimplePathWithPathVariable(@PathVariable String id) {
   return "Get a specific Foo with id=" + id;

Note that @PathVariable benefits from automatic type conversion, so we could have also declared the id as:

@PathVariable long id

4.2. Multiple @PathVariable

More complex URI may need to map multiple parts of the URI to multiple values:

@RequestMapping(value = "/ex/foos/{fooid}/bar/{barid}")
public String getFoosBySimplePathWithPathVariables
  (@PathVariable long fooid, @PathVariable long barid) {
    return "Get a specific Bar with id=" + barid + " from a Foo with id=" + fooid;

This is easily tested with curl in the same way:

curl http://localhost:8080/spring-rest/ex/foos/1/bar/2

4.3. @PathVariable with RegEx

Regular expressions can also be used when mapping the @PathVariable; for example, we will restrict the mapping to only accept numerical values for the id:

@RequestMapping(value = "/ex/bars/{numericId:[\d]+}")
public String getBarsBySimplePathWithPathVariable(@PathVariable final long numericId) {
    return "Get a specific Bar with id=" + numericId;

This will mean that the following URIs will match:


But this will not:


5. RequestMapping with Request Parameters

@RequestMapping allows easy mapping of URL parameters with the @RequestParam annotation.

We are now mapping a request to an URI such as:

@RequestMapping(value = "/ex/bars")
public String getBarBySimplePathWithRequestParam(@RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;

We are then extracting the value of the id parameter using the @RequestParam(“id”) annotation in the controller method signature.

The send a request with the id parameter, we’ll use the parameter support in curl:

curl -i -d id=100 http://localhost:8080/spring-rest/ex/bars

In this example, the parameter was bound directly without having been declared first.

For more advanced scenarios, @RequestMapping can explicitly define the parameters to be mapped as yet another way of narrowing the request mapping:

@RequestMapping(value = "/ex/bars", params = "id")
public String getBarBySimplePathWithExplicitRequestParam(@RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;

Even more flexible mappings are allowed – multiple params values can be defined, and not all of them have to be used:

@RequestMapping(value = "/ex/bars", params = { "id", "second" })
public String getBarBySimplePathWithExplicitRequestParams(@RequestParam("id") long id) {
    return "Narrow Get a specific Bar with id=" + id;

And of course, a request to an URI such as:


Will always be mapped to the best match – which is the narrower match, which defines both the id and the second parameter.

6. RequestMapping Corner Cases

6.1. @RequestMapping – multiple paths mapped to the same controller method

Although a single @RequestMapping path value is usually used for a single controller method, this is just good practice, not a hard and fast rule – there are some cases where mapping multiple requests to the same method may be necessary. For that case, the value attribute of @RequestMapping does accept multiple mappings, not just a single one:

@RequestMapping(value = { "/ex/advanced/bars", "/ex/advanced/foos" })
public String getFoosOrBarsByPath() {
    return "Advanced - Get some Foos or Bars";

Now, both of these curl commands should hit the same method:

curl -i http://localhost:8080/spring-rest/ex/advanced/foos
curl -i http://localhost:8080/spring-rest/ex/advanced/bars

6.2. @RequestMapping – multiple HTTP request methods to the same controller method

Multiple requests using different HTTP verbs can be mapped to the same controller method:

@RequestMapping(value = "/ex/foos/multiple", method = { RequestMethod.PUT, RequestMethod.POST })
public String putAndPostFoos() {
    return "Advanced - PUT and POST within single method";

With curl, both of these will now hit the same method:

curl -i -X POST http://localhost:8080/spring-rest/ex/foos/multiple
curl -i -X PUT http://localhost:8080/spring-rest/ex/foos/multiple

6.3. @RequestMapping – a fallback for all requests

To implement a simple fallback for all requests using a specific HTTP method:

@RequestMapping(value = "*")
public String getFallback() {
    return "Fallback for GET Requests";

Or even for all request:

@RequestMapping(value = "*", method = { RequestMethod.GET, RequestMethod.POST ... })
public String allFallback() {
    return "Fallback for All Requests";

7. Spring Configuration

The Spring MVC Configuration is simple enough – considering that our FooController is defined in the following package:

package org.baeldung.spring.web.controller;

public class FooController { ... }

Starting with Spring 3.1, we will only need a @Configuration class to enable the full MVC support and configure classpath scanning for the controller:

@ComponentScan({ "org.baeldung.spring.web.controller" })
public class MvcConfig {

8. Conclusion

This article focus on the @RequestMapping annotation in Spring - discussing a simple usecase, the mapping of HTTP headers, binding parts of the URI with @PathVariable and working with URI parameters and the @RequestParam annotation.

The implementation of this Spring Request Mapping Tutorial can be downloaded as a working sample project.

This is an Eclipse based project, so it should be easy to import and run as it is.

I usually post about Spring stuff on Twitter - you can follow me there:

Get the eBooks and Learn to Build a Simple App
Build a Simple but Working App with Spring


  • http://www.facebook.com/pvmhoang Pham Vu Minh Hoang

    sorry, how i can get source code from git, i have try but i cann’t

    • http://www.baeldung.com/ Eugen Paraschiv

      The link goes into the relevant submodule of the project – you need
      to go back one level (click on tutorials) and you’ll see the git access
      URI – wich you can use to clone the project:

  • http://codyburleson.com/ Cody Burleson

    I really love the way you structured this post. It is extremely informative in a way that’s very easy to scan. I learned a few things I didn’t know about Spring, which I’ve been using for quite a long time now, in just minutes. Thanks for taking the time to share!

    • http://www.baeldung.com/ Eugen Paraschiv

      I’m glad you found the article helpful.

  • grooha

    OK, but what’s about multiple values pass in a 1 param, e.g.? http://…/age=23&fav=12&fav=15

    As you can see, we have two parameters: age, and fav. The fav param. has two values: 12, and 15. Suppose, that there is a class:

    public class MyClass {
    private int age;
    private int fav;


    No problem with a single value for fav – it will be binded to int fav in the MyClass class. But in that case we have two values… I suppose, Spring MVC will bind only the first value (12) to fav, right? What should I do to make this code working?

    • http://www.baeldung.com/ Eugen Paraschiv

      Interesting question – if you have a choice, I would suggest keeping the parameter names unique (you can have the values as comma separated and then parse them out). If that’s not an option, I would try to map it to an array – and if Spring isn’t able to do so, you can always open a JIRA.
      You can always go lower level and simply inject into your controller method the http request, and parse out the parameters yourself.

      • grooha

        Thanks for your answer. I’ve considered parsing out all needed params in my controller, maybe it will be the best choice. I will let you know and publish a working solution – maybe it will help someone in the future. Thanks again!

  • http://norbertherczeg.me Norbert Csaba Herczeg

    In receiver type operations :headers = “Accept=application/json” instead of defining MIME types by hand you can use consumes = MediaType.APPLICATION_JSON_VALUE.

    This way it’s really easy to refactor, and more error/typo free! :)

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Norbert – yeah, I do that in code, but in the article I wanted to have the samples as readable as possible – so going for the raw text is a bit easier to read and understand. Thanks for the suggestion – cheers,

  • Manish Sahni

    Hi Eugen,
    Nice informative artice on Rest .How can we pass a Object from the client and handle it in the Rest using Spring.I am new to Rest and seen some articles hat describes we can send it as a JSON string or XML.
    Is thier any other way to achieve this other than these ?

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Manish – sure, you can map an object passed in the body of the request in your controller layer – you’ll need to use the @RequestBody annotation for that. You can check out this introductory article to see how that works. Hope it helps. Cheers,