Request Mapping & Parameters

Bind data from the request: @PathVariable for path segments, @RequestParam for query strings, @RequestBody for JSON payloads, and the right status codes for each operation.

Learn Request Mapping & Parameters in our free Java course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick…

Part of the free Java course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Before You Start

Finish Building REST Controllers first — this lesson builds on @RestController , @GetMapping / @PostMapping and ResponseEntity .

What You'll Learn

The Big Idea — Filling Out a Delivery Form

💡 Analogy: A request is like a delivery form. The address line (path) names exactly which house — that's your @PathVariable . The delivery options ticked at the bottom (query string) are your @RequestParam . The parcel itself (the body) is your @RequestBody . Spring reads the form and hands each part to the right method parameter.

Status codes are the courier's receipt: 201 "delivered & created", 404 "no such address", 204 "done, nothing to hand back".

1️⃣ Path Variables with @PathVariable

A templated segment like /users/ {id} is captured with @PathVariable . Use this to identify a specific resource — the path is part of its identity.

2️⃣ Query Parameters with @RequestParam

@RequestParam binds query-string values like ?q=ann&page=2 . Add required=false or defaultValue to make a parameter optional.

3️⃣ Request Bodies with @RequestBody

For POST/PUT, @RequestBody deserialises the JSON body into a record or POJO via Jackson. Pair it with a 201 Created status for new resources.

4️⃣ The Binding, Made Concrete

Here is what each binding produces, simulated in plain Java so the path / query / body distinction is unmistakable.

🧠 Quick Recall

Answer: @PathVariable for the path segment, @RequestParam for the query string.

Answer: @RequestBody deserialises it via a message converter (Jackson).

Common Errors

• ❌ Mismatched names. {id} but a differently named variable. Fix: match names or use @PathVariable("id") .
• ❌ Missing required @RequestParam. Yields 400. Fix: set required=false or a defaultValue.
• ❌ Forgetting @RequestBody. The JSON isn't bound. Fix: annotate the body parameter.
• ❌ Returning 200 for everything. Misleads clients. Fix: use 201/204/404 appropriately.
• ❌ Using @RequestParam for the body. Wrong source. Fix: @RequestBody for JSON payloads.

Pro Tips

• 💡 Path for identity, query for modifiers — a clean, conventional split.
• 💡 Use defaultValue to avoid null checks on optional params.
• 💡 Validate request bodies with @Valid and Bean Validation annotations.
• 💡 Return Location headers with 201 so clients can fetch the new resource.

📋 Quick Reference

Bind

Annotation

Source

path segment

@PathVariable

/users/ {id}

query string

@RequestParam

?q=ann&page=2

JSON body

@RequestBody

POST/PUT payload

header

@RequestHeader

Named HTTP header

fixed status

@ResponseStatus

Constant code

created

201 Created

Successful POST

missing

404 Not Found

No such resource

📚 Resources / Keep Learning

• 📘 Handler Method Arguments — Spring MVC docs
• 📗 Mapping Requests — Spring MVC docs
• 📗 Building REST services with Spring — tutorial

❓ Frequently Asked Questions

🎉 Lesson Complete!

You can now bind every part of a request — path segments (@PathVariable), query strings (@RequestParam), JSON bodies (@RequestBody) and headers (@RequestHeader) — and return correct HTTP status codes for each operation.

Next up: The Service Layer — where business logic lives, separated from the web layer.

Practice quiz

Continue this course

• Previous: Building REST Controllers
• Next: The Service Layer