When to Use Body vs Params in Spring Boot APIs: A Practical Guide

During API design and development, choosing between Body parameters and Params parameters is a common challenge. Different Content‑Type settings correspond to different data‑processing logic and code implementations. Misunderstanding these differences can cause request failures, missing parameters, or data format errors.

Tools like Apifox and Postman require you to specify request parameters and request bodies, typically using either Query (Params) or Body. Body can be x‑www‑form‑urlencoded, form‑data, binary, or JSON, each with its own handling method.

Spring Boot Request Handling

Params

@GetMapping(value = "/query")
public String getQueryParams(@RequestParam String name, @RequestParam int age) {
    return "Name: " + name + ", Age: " + age;
}

@GetMapping(value = "/query")
public String getQueryParams(@ModelAttribute User user) {
    return "Name: " + user.getName() + ", Age: " + user.getAge();
}

@Data
public static class User {
    private String name;
    private Integer age;
}

Body

x-www-form-urlencoded

@PostMapping(value = "/form", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public String getQueryParams(@RequestParam String name, @RequestParam Integer age) {
    return "Name: " + name + ", Age: " + age;
}

@PostMapping(value = "/form", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public String getQueryParams(@ModelAttribute User user) {
    return "Name: " + user.getName() + ", Age: " + user.getAge();
}

form-data

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String uploadFiles(@RequestParam String name,
                          @RequestParam("file") MultipartFile file,
                          @RequestParam("files") MultipartFile[] files) {
    return "name:" + name + ", Uploaded :" + file.getOriginalFilename() + ", files :" + files.length;
}

binary

@PostMapping(value = "/uploadBinary", consumes = MediaType.APPLICATION_OCTET_STREAM_VALUE)
public ResponseEntity<String> uploadBinary(@RequestBody byte[] fileData) {
    return ResponseEntity.ok("Received binary file of size: " + fileData.length);
}

json

@PostMapping(value = "/json", consumes = MediaType.APPLICATION_JSON_VALUE)
public String postJson(@RequestBody User user) {
    return "Received user: " + user.getName() + ", Age: " + user.getAge();
}

Another approach reads the raw InputStream for any request type and parses URL‑encoded parameters manually.

@PostMapping(value = "/post", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public Map<String, String> handlePostStream(HttpServletRequest request) throws Exception {
    String body = new BufferedReader(new InputStreamReader(request.getInputStream()))
        .lines().collect(Collectors.joining("
"));
    Map<String, String> paramMap = Arrays.stream(body.split("&"))
        .map(param -> param.split("="))
        .filter(pair -> pair.length == 2)
        .collect(Collectors.toMap(pair[0], pair[1] -> {
            try {
                return URLDecoder.decode(pair[1], StandardCharsets.UTF_8.toString());
            } catch (UnsupportedEncodingException e) {
                e.printStackTrace();
                return null;
            }
        }));
    return paramMap;
}

Summary of when to use each format:

✅ Query – suitable for GET request parameters.

✅ x-www-form-urlencoded – suitable for simple form submissions.

✅ form-data – suitable for multiple file uploads and additional fields.

✅ binary – suitable for single file or streaming transfers, such as large files or video streams.

✅ JSON – suitable for complex object transmission, the modern API standard.

Using Params or Body is independent of GET or POST methods.