Desenvolvendo APIs REST com Spring Boot: Tratamento de Parâmetros de Requisição

Quando se trata de desenvolver APIs REST utilizando o Spring Boot, um dos aspectos mais importantes a dominar é o tratamento adequado dos parâmetros de requisição. Esses parâmetros são essenciais para a comunicação entre o cliente e o servidor, permitindo que os usuários forneçam informações que influenciam o comportamento da API.

Entendendo os Tipos de Parâmetros de Requisição

Existem diferentes tipos de parâmetros de requisição que podem ser utilizados em uma API REST:

• Query Parameters: São incluídos na URL após o símbolo '?'. Eles são usados para filtrar recursos ou modificar a resposta de alguma forma. Exemplo: /users?age=25
• Path Variables: São usados para identificar um recurso específico dentro de uma coleção de recursos. Eles são parte da URL. Exemplo: /users/{userId}
• Request Body: Contém dados enviados em formato JSON ou XML que são utilizados para criar ou atualizar recursos.
• Request Headers: Fornecem informações adicionais sobre a requisição, como tipo de conteúdo ou autenticação.

Tratando Query Parameters

No Spring Boot, os query parameters podem ser facilmente tratados com a anotação @RequestParam. Esta anotação pode ser usada para mapear parâmetros de consulta individuais para os parâmetros do método em um controlador. Por exemplo:

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(@RequestParam(value = "age", required = false) Integer age) {
    // Lógica para filtrar usuários pela idade
    return ResponseEntity.ok(userService.getUsersByAge(age));
}
    

Se o parâmetro 'age' não for fornecido, o valor será null e a API pode retornar todos os usuários. Se for fornecido, a API filtrará os usuários pela idade especificada.

Tratando Path Variables

Para tratar path variables, o Spring Boot utiliza a anotação @PathVariable. Isso permite que você extraia valores de partes variáveis da URL. Veja o exemplo abaixo:

@GetMapping("/users/{userId}")
public ResponseEntity<User> getUserById(@PathVariable Long userId) {
    // Lógica para buscar um usuário pelo ID
    return ResponseEntity.ok(userService.getUserById(userId));
}
    

O valor de {userId} na URL é vinculado ao parâmetro userId do método.

Tratando Request Body

Para lidar com dados enviados no corpo da requisição, como JSON ou XML, usamos a anotação @RequestBody. Isso permite que o Spring Boot deserializa automaticamente o corpo da requisição para um objeto Java. Por exemplo:

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User newUser) {
    // Lógica para criar um novo usuário
    return ResponseEntity.status(HttpStatus.CREATED).body(userService.createUser(newUser));
}
    

Aqui, o JSON enviado na requisição é convertido para um objeto User.

Tratando Request Headers

Headers de requisição podem ser tratados usando a anotação @RequestHeader. Isso é útil para extrair informações como tokens de autenticação ou tipos de conteúdo. Veja um exemplo:

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(@RequestHeader(value = "Authorization") String authToken) {
    // Lógica para autenticar o usuário com o token fornecido
    return ResponseEntity.ok(userService.getAuthenticatedUsers(authToken));
}
    

Este método extrai o valor do header 'Authorization' e o utiliza para autenticar o usuário antes de retornar a lista de usuários.

Validação de Parâmetros

Além de simplesmente tratar os parâmetros, muitas vezes é necessário validá-los. O Spring Boot suporta a integração com o Bean Validation API para validar parâmetros de requisição. Por exemplo:

@PostMapping("/users")
public ResponseEntity<User> createUser(@Valid @RequestBody User newUser) {
    // Lógica para criar um novo usuário
    return ResponseEntity.status(HttpStatus.CREATED).body(userService.createUser(newUser));
}
    

Aqui, o objeto User será validado contra as restrições definidas em suas anotações de validação (como @NotNull, @Size, etc.) antes de ser processado pelo método.

Conclusão

O tratamento adequado dos parâmetros de requisição é um aspecto fundamental no desenvolvimento de APIs REST com Spring Boot. Compreender como utilizar as anotações @RequestParam, @PathVariable, @RequestBody e @RequestHeader, bem como a validação de parâmetros, permite criar APIs robustas e flexíveis que podem atender às necessidades dos usuários de forma eficiente.